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About This Manual 


Purpose 


This manual is an in-depth technical reference for system programmers 
creating Windows applications. This manual is intended to be used with 
the Microsofte Windows Programming Guide. The guide explains the Win- 
dows system and illustrates how to create Windows applications. 


It is assumed that all readers have some programming knowledge and 
experience. 


Using This Manual 


This manual contains eight chapters, three appendixes, and an index. Each 
part is briefly described below: 


Chapter 1 Provides an overview of this manual. 

Chapter 2 Describes the routines used to create and use windows. 
Chapter 3 Describes the Graphics Device Interface (GDI) routines. 
Chapter 4 Describes the routines used to access system resources. 


Chapter 5 Describes the data types and structures used by the 
Windows routines. 


Chapter 6 Describes the formats for input files used by Windows. 


Chapter 7 Describes the assembly language macros used to develop 
assembly language Windows applications. 


Chapter 8 Describes Windows messages. 
Appendix A Lists the raster operation codes and their definitions. 


Appendix B Lists the standard Windows key codes and their 
definitions. 


Appendix C Describes the font files and their format. 


Chapter 1 
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Introduction 


1.1 Introduction 


This manual describes the functions, data types, data structures, files, and 
assembly-language macros used by Window applications to access the Win- 


dows system. 


1.2 Notational Conventions 


The following notational conventions are observed throughout this manual: 


Convention 


boldface 


ttalics 


(Parentheses) 


Meaning 


Boldface is used for keywords, such as function, 
data type, structure, and macro names. These 
names are spelled exactly as they should appear in 
source programs. For example, in 


ReleaseCapture{ ) 


ReleaseCapture is bold to indicate that it is the 
name of a function. 


Italics are used for placeholders, i.e., descriptive 

names that represent parameters or variables that 

the programmer must supply. For example, in 
Reply Message( /Reply ) 

[Reply is a parameter passed to the Reply Message 

function. 


Parentheses enclose the list of parameters to be 
passed to a function. For example, in 


ScreenToClient( hWnd,'lpPotnt ) 


hWnd and [pPoint are parameters to be passed to 
the ScreenToClient function. 


The colon separates a function’s parameter list 
from the return value. Return values always appear 
after the colon. For example, 


GetMenu(hWnd):hMenu 


indicates that the value of hMenu is to be returned 
when GetMenu is called. 
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1.3. Naming Conventions 


Many Windows functions have been named using a verb-noun model to help 
you remember and become familiar with the function. The function name 
indicates both what the function does (verb) and the target of its action 
(noun). All function names begin with an uppercase letter. If the name is 
composed of several words, each word begins with an uppercase letter and 
all words are butted up against each other (no spaces or underscore charac- 
ters to separate words). Some examples of function names are shown 
below: 


RegisterClass 
Create Window 
Set MapMode 


1.4 Data Types 


Most parameters and local variables have a lowercase prefix that indicates 
the general type of the parameter, followed by one or more words that 
describe the content of the parameter. The standard prefixes used in 
parameter and variable names are defined below: 


Prefix Meaning 

c character (a one-byte value) 

b Boolean (a nonzero value means true, zero means 
false) 

f bit flags packed into a 16-bit integer 

n short (16-bit) integer 

l long (32-bit) integer 

W short (16-bit) unsigned integer 

dw long (32-bit) unsigned integer 

h 16-bit handle 
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p short (16-bit) pointer 

Ip long (32-bit) pointer 

pt for X,Y coordinates packed into an unsigned 32-bit 
integer 

rgb for an rgb color value packed into 32-bit integer 


If no lowercase prefix is given, the parameter is a short integer whose name 
is descriptive. 


Some examples of parameter and variable names are shown below: 


bIconic 
fAction 
nBytes 


hWnd 
lpString 


1.5 Windows Calling Convention 


Windows uses the same calling convention used by Microsoft" Pascal. 
Throughout this manual this calling convention will be referred to as the 
“Pascal” calling convention. The Pascal calling convention entails the fol- 


lowing: 


e Parameters are pushed onto the stack in the order in which they 
appear in the function call. 


e The code that restores the stack is part of the called function 
(rather than the caller). 


This convention differs from the calling convention used in other languages 
such as C. In C, parameters are are pushed onto the stack in reverse order, 
and the calling function is responsible for restoring the stack. 
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When developing Windows applications in a language such as C that does 
not ordinarily use the Pascal calling convention, you must ensure that the 
Pascal calling convention is used for any function that is called by Win- 
dows. In C, this requires the use of the PASCAL keyword when the func- 
tion is declared. 


1.6 Near and Far Pointers 


A “near” pointer is a short pointer (16 bits) that consists of just an offset 
from one of the current segment register values. A “far” pointer is a long 
pointer (32 bits) that consists of a full segmented address: the segment 
address 1s in the high-order word, and the offset is in the low-order word. 
The default size of pointers in your program depends on the language you 
are using and the memory model. 


In some cases Windows explicitly requires a far pointer. In particular, 
whenever you pass Windows a pointer to a function that will later be called 
back by Windows, the pointer must be a far pointer. (The reference 
manual tells you when a far pointer is required.) 


To obtain a far pointer when the default size of your pointers is near, you 
must explicitly declare the pointer to be a far pointer. See your language 
documentation for details on declaring far pointers. 


Chapter 2 


Window Functions 


2.1 
2.2 
2.3 
2.4 
2.0 
2.6 
2.1 
2.8 
2.9 
2.10 
2.11 
212 
213 
2.14 
2.15 
2.16 
ZAG 
2.18 
2.19 
2.20 
2.21 
2.22 
2.23 


Introduction 9g 

Main Function g 

Message Functions 10 

Window function 20 

Default Window Function 21 
Window Class Functions 22 
Window Creation Functions 26 
Window Display and Movement Functions 
Dialog Box Functions 39 

Clipboard Functions 47 

Input Functions 55 

Menu [unctions 61 

Window Painting Functions — 70 
Scrolling Functions 77 

Property List Functions 81 
Window Attribute Functions 84 
Error Functions 87 

Cursor I'unctions 90 

Caret Functions 92 

Coordinate Functions 95 
Rectangle I’unctions 97 

System Information Functions 100 
Window Hook Function 103 


J2 


Window Functions 


2.1 Introduction 


This chapter describes how to create and control windows in Windows 
applications. An application controls its own execution by reading mes- 
sages from the application queue and dispatching the message to an 
appropriate window function. Messages not handled by the application are 
sent to a default window function supplied by Windows. 


2.2 Main Function 


The main function is an application-supplied function that serves as the 
entry point for program execution. Usually, the WinMain initializes the 
application, then controls the application’s execution by processing mes- 
sages from the Windows application queue. 


Every application must have a main function of the form and function 
described below. 


WinMain ( Alnstance, hPrevinstance, lpCmdLine, nCmdShow ) : nExitCode 


Purpose This function is the entry point for execution of a Windows 
application. Typically, the WinMain function initializes 
the application’s data, registers the application’s window 
class, creates and displays a window, then enters a loop to 
process messages from the Windows application queue. 


The loop continues until a WM_ QUIT message is received 
(either through calling PostQuitMessage or through 
receiving a nonzero return value from GetMessage.) When 
this occurs, the WinMain function must exit, passing the 
wParam parameter of the message to Windows as the exit 
value. 


Parameters hinstance is the instance handle of the new instance. 


hPrevinstance is the module instance handle of the previous 
module instance. It is NULL if this is the first instance. 


lynCmdLine is a long pointer to a null-terminated command 
line. 


nCmdShow is a short integer value specifying whether or not 
the window should be initially displayed, left iconic, or hid- 
den. The parameter must be passed to the Show Window 
function after the application’s window has been created. 
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Return Value nHaitCode is the wParam value from the last message 


Notes 


received (the message to quit the window). 


The WinMain function must use the Pascal calling conven- 
tion. 


WinMain does not have to be exported. 


2.3 Message Functions 


Applications use the message functions to read and process the messages in 
the application queue. 


PostQuitMessage ( nExitCode ) 


Purpose 


Parameter 


This function informs Windows that the application wishes 
to terminate execution. It is typically used in response to a 


WM_ DESTROY message. 


PostQuitMessage posts a WM_ QUIT message to the 
application and returns immediately; the function merely 
informs the system that the application wants to quit some- 
time in the future. 


When the application receives the WM_ QUIT message, it 
should exit the message loop in the main function and 
return control to Windows. The exit code returned to Win- 
dows must be the nParam parameter of the WM_ QUIT 
message. 


nEztCode is the wParam parameter of the WM_ QUIT mes- 


Sage. 


Return Value None. 


GetMessage ( [pMsg, hWnd, wMsgFilterMin, wMsgFilterMaz ) : bContinue 


Purpose 
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This function retrieves a message from the application queue 
and places the message in the data structure pointed to by 
lnMsg. If no message is available, GetMessage yields con- 
trol to other applications until a message becomes available. 


Get Message retrieves only messages associated with the 
window specified by hWnd and within the range of message 
values given by wMsgFilterMin and wMsgl'ilterMaz. If hWnd 
is NULL, GetMessage retrieves messages for any window 
belonging to the application making the call. (GetMessage 


Parameters 


Return Value 


Notes 
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does not retrieve messages for windows belonging to other 
applications.) If wMsgFtlterMin and wMsgFilterMaz are both 
0, GetMessage returns all available messages (no filtering 
is performed). 


The constants WM_KEYFIRST and WM_ KEYLAST can 
be used as filter values to retrieve all messages related to 
keyboard input; WM_ MOUSEFIRST and 

WM_ MOUSELAST can be used to retrieve all mouse- 


related messages. 
lnMsg is a long pointer to a MSG data structure. 


hWnd is a handle to the window whose messages are to be 
examined. If hWnd is NULL, GetMessage retrieves mes- 
sages for any window belonging to the application making 
the call. 


wMsgFilterMin is an unsigned short integer value specifying 
the lowest message to be examined. 


wMsgFilterMaz is an unsigned short integer value specifying 
the highest message to be examined. 


bContinue, a Boolean value, is nonzero if a message other 
than WM_ QUIT is retrieved. It is zero if the WM_ QUIT 


message is retrieved. 


The return value is usually used to decide whether to ter- 
minate the application’s main loop and exit the program. 


In addition to yielding control to other applications when no 
messages are available, GetMessage and PeekMessage 


also yield control when WM_ PAINT or WM_ TIMER mes- 


sages are available. 


The GetMessage, PeekMessage, and WaitMessage func- 
tions are the only way to let other applications run. If your 
application does not call any of these functions for long 
periods of time, other applications do not get a chance to 
run. 


When GetMessage, PeekMessage, and WaitMessage 
yield contro] to other applications, the stack and data seg- 
ments of the application calling the function may move in 
memory to accommodate the changing memory require- 
ments of other applications. If the application has stored 
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long pointers to objects in the data or stack segment (1.e., 
global or local variables), these pointers can become invalid 
after a call to GetMessage, PeekMessage, or WaitMes- 
sage. However, the /pMsg parameter of the called function 
remains valid in any case. 


PeekMessage ( [pMsg, hWnd, wMsgFilterMin, wMsgf'tlterMaz, 


Purpose 


Parameters 


Return Value 


Notes 
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bRemoveMsg ): bPresent 


This function checks the application queue for a message 
and places the message (if any) in the data structure pointed 
to by lpMsg. PeekMessage returns immediately, whether a 
message is present or not. 


PeekMessage retrieves only messages associated with the 
window specified by hWnd and within the range of message 
values given by wMsgl'tlterMin and wMsgltlterMaz. If hWnd 
is NULL and wMsglilterMin and wMsgltlterMaz are both 0, 


PeekMessage checks the entire queue for messages. 


The constants WM_ KEYFIRST and WM_KEYLAST can 
be used as filter values to get all key messages; 
WM_ MOUSEFIRST and WM_MOUSELAST can be used to 


get all mouse messages. 


lnMsgq is a long pointer to a data structure having MSG 
type. 


hWnd is a handle to the window whose messages are to be 
examined. 


wMsgFilterMin is an unsigned short integer value specifying 
the lowest. message to be examined. 


wMsgFilterMaz is an unsigned short integer value specifying 
the highest position to be examined. 


bRemoveMsg is a Boolean value that determines whether or 
not the message should be removed from the application 
queue. If bRemoveMsg is nonzero, the message is removed. If 
zero, it remains in the queue and can be read by the next 
call to GetMessage or Peek Message. 


bPresent, a Boolean value, is nonzero if a message is avail- 
able. Otherwise, it Is zero. 


WM_— PAINT messages cannot be removed from the queue 
using PeekMessage. They remain in the queue until pro- 
cessed. 


Window Functions 


The GetMessage, PeekMessage, and WaitMessage func- 
tions yield control to other applications. These calls are the 
only way to let other applications run. If your application 
does not call any of these functions for long periods of time, 
other applications do not get a chance to run. 


When GetMessage, PeekMessage, and WaitMessage 
yield control to other applications, the stack and data seg- 
ments of the application calling the function may move in 
memory to accommodate the changing memory require- 
ments of other applications. If the application has stored 
long pointers to objects in the data or stack segment (i.e., 
global or local variables), these pointers can become invalid 
after a call to GetMessage, PeekMessage, or WaitMes- 
sage. However, the /pMsg parameter of the called function 
remains valid in any case. 


WaitMessage ( ) 


Purpose 


Parameters 
Return Value 
Notes 


This function is used to yield control to other applications 
when an application has no other tasks to perfotm. Wait- 
Message suspends the application and does not return until 
a new message is placed in the application’s queue. 


None. 
None. 


The construction 


if (!PeekMessage(...)) 
WaitMessage (); 


is equivalent to a call to GetMessage. 


The GetMessage, PeekMessage, and WaitMessage func- 
tions yield control to other applications. These calls are the 
only way to let other applications run. If your application 
does not call any of these functions for long periods of time, 
other applications do not get a chance to run. 


When GetMessage, PeekMessage, and WaitMessage 
yield control to other applications, the stack and data seg- 
ments of the application calling the function may move in 
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memory to accommodate the changing memory require- 
ments of other applications. If the application has stored 
long pointers to objects in the data or stack segment (i.e., 
global or local variables), these pointers can become invalid 
after a call to GetMessage, PeekMessage, or 

Wait Message. 


GetMessagePos ( }: ptPos 


Purpose 


Parameters 


This function returns a long value representing the mouse 
position, in screen coordinates, when the last message 
obtained by GetMessage occurred. 


None. 


Return Value ptPosis an unsigned long value containing the x and y coor- 


Notes 


dinates of the mouse position. The x coordinate is in the 
low-order word and the y coordinate is in the high-order 
word. If the return value is assigned to a variable, the 
MAKEPOINT macro can be used to obtain a POINT struc- 
ture from ptPos; the LOWORD or HIWORD macro can be 


used to extract the x or the y coordinate. 


To obtain the current position of the mouse cursor instead 
of the position when the last message occurred, use the 
GetCursorPos function. 


GetMessageTime ( ): /7:1me 


Purpose 


Parameters 
Return Value 
Notes 
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This function returns the message time for the last message 
retrieved by GetMessage. The message time is a long 
integer specifying the elapsed time (in milliseconds) since 
the system was booted to the time the message was created 
(placed in the application queue). 


None. 
[Time is a long integer value specifying the message time. 


Do not assume that the /Time value is always increasing. If 
the system has been on a long time, the /7Time value may be 
“wrapped around” to start again at zero. To calculate time 
delays between messages, subtract the time of the second 
message from the time of the first message. 
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GetCurrentTime ( }: /Time 


Purpose 


Parameters 


Return Value 


Notes 


This function returns the time elapsed since the system was 
booted to the current time. 


None. 


(Time is a long integer specifying the elapsed time in mil- 
liseconds. 


The value returned by GetCurrent Time is in the same 
units as the value returned by GetMessageTime. For 
instance, these two values can be subtracted to determine 
the time elapsed since a message occurred. 


TranslateMessage ( [pMsg ): bTranslated 


Purpose 


Parameters 


Return Value 


Notes 


This function translates virtual keystroke messages into 
character messages, as follows: 


e WM_KEYDOWN and WM_KEYUP messages are 
translated into WM_ CHAR and WM_ DEADCHAR 


messages. 


e WM_SYSKEYDOWN and WM_SYSKEYUP are 
translated into WM_SYSCHAR and 
WM_SYSDEADCHAR messages. 


The character messages are posted to the application queue, 
to be read the next time the application calls GetMessage 
or PeekMessage. 


lpMsg is a long pointer to a data structure with MSG type, 
retrieved through GetMessage or PeekMessage. 


bTranslated, a Boolean value, is nonzero if the message was 
translated (i.e., character messages were posted to the appli- 
cation queue). Otherwise, 6Translated is zero. 


TranslateMessage does not modify the message given by 
loMszq. | 


An application should not call TranslateMessage if the 
application processes virtual key messages for some other 
purpose. For instance, an application should not call 
TranslateMessage if TranslateAccelerator returns 
nonzero. 
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TranslateAccelerator (hWnd, hAccTable, lpMsg ): bTranslated 


Purpose 


Parameters 


Return Value 


Notes 
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This function processes keyboard accelerators for menu com- 
mands. It translates WM_KEYUP and WM_KEYDOWN 
messages to WM_ COMMAND or WM_SYSCOMMAND 
messages, if there is an entry for the key in the application’s 
accelerator table. The high-order word of the [Param 
parameter of the WM_SYSCOMMAND or 

WM_ COMMAND message contains the value 1 to 
differentiate the message from messages sent by menus or 
controls. 


The WM_ COMMAND or WM_SYSCOMMAND messages 
are sent directly to the window, rather than being posted to 
the application queue. TranslateAccelerator does not 
return until the command is processed. 


Accelerator keystrokes that are defined to select items from 
the system menu are translated into WM_SYSCOMMAND 
messages; all other accelerators are translated into 


WM_ COMMAND messages. 


hWnd is a handle to the window whose messages are to be 
translated. 


hAccTable is a handle to an accelerator table (loaded using 
LoadAccelerators). 


lnMsgq is a long pointer to a message retrieved using Get- 
Message or PeekMessage. The message must be a data 
structure having MSG type. 


6Translated, a Boolean value, is nonzero if translation 
occurred, zero otherwise. 


When TranslateAccelerator returns nonzero (meaning 
that the message was translated), the application should 
NOT process the message again using TranslateMessage. 


Commands in accelerator tables do not have to correspond 
to menu items. | 


If the accelerator command does correspond to a menu item, 
the application is sent WM_INITMENU and 
WM_INITMENUPOPUP messages, just as if the user were 
trying to pull down the menu. However, these messages are 
not sent if any of the following conditions hold: 
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e The window is disabled. 
e The menu item ts disabled. 


e The command is not in the system menu and the 
window is iconic. 


e A mouse capture is in effect (see SetCapture). 


If the window is the active window and there is no keyboard 
focus (generally true if the window is iconic), then 
WM_SYSKEYUP and WM_SYSKEYDOWN messages are 
translated instead of WM_KEYUP and WM_KEYDOWN 


messages. 


If an accelerator keystroke corresponding to a menu item 
occurs when the window owning the menu is iconic, no 
WM_ COMMAND message is sent. However, if an accelera- 
tor keystroke occurs that does not match any of the items 
on the window’s menu or on the system menu, a 


WM_ COMMAND message is sent, even if the window is 


iconic. 


DispatchMessage ( l[pMszq ): [Result 


Purpose 


Parameters 


Return Value 


This function passes the message in the MSG structure 
pointed to by lpMsg to the window function of the specified 
window. 


lnMsg is a long pointer to a data structure having MSG 
type. The structure must contain valid message values. 


If lpMsg points to a WM_ TIMER message and the lParam 
parameter of the WM_ TIMER message is not NULL, then 
the [Param parameter is the address of a function which is 
called instead of the window function. 


[Reply, a long value, is the value returned by the window 
function. Its meaning depends on the message being 
dispatched, but generally (Reply is ignored. 


SendMessage ( hWnd, wMsg, wParam, lParam ): lReply 


Purpose 


This function sends a message to a window or windows. 
SendMessage does not return until the message has been 
processed. If the window receiving the message is part of 
the same application, the window function is called immedi- 
ately, as a subroutine. 
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Parameters 


Return Value 


Post Message 


Purpose 


Parameters 


Return Value 
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If the window is part of another task, Windows switches to 
the appropriate task and calls the appropriate window func- 
tion, passing the message to the window function. The mes- 
sage is not placed in the destination application’s queue. 


hWnd is the handle of the window to receive the message. If 
the hWnd parameter is FFFF (hexadecimal), the message is 
sent to all tiled or popup windows in the system. (The mes- 
sage is not sent to child windows.) 


wMsgq is an unsigned short integer specifying the message to 
be set. 


wParam is an unsigned short integer specifying additional 
message information. 


[Param is a 32-bit integer specifying additional message 
information. 


lReply, a long integer, is the value returned by the window 
function that received the message. Its value depends on 
the message being sent. 


( hWnd, wMsg, wParam, lParam ): bPosted 


This function places a message in a window’s application 
queue and returns without waiting for the corresponding 
window to process the message. The posted message can be 
retrieved by calls to GetMessage or PeekMessage. 


hWnd is the handle of the window to receive the message. If 
the hWnd parameter is FF FF (hexadecimal), the message is 
sent to all tiled or popup windows in the system. (The mes- 
sage is not sent to child windows.) 


wMsg is an unsigned short integer specifying the type of 
message posted. 


wParam is a short integer value specifying additional mes- 
sage information. 


{Param is a long integer value specifying additional message 
information. 


bPosted, a Boolean value, is nonzero if the message is posted. 
Otherwise, it is zero. 
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Reply Message ( /Reply ) 


Purpose 


Parameters 


This function is used to reply to a message sent through 
SendMessage without returning control to the function 
calling SendMessage. Ordinarily, SendMessage waits for 
the return value of the function to which the message was 
sent. ReplyMessage allows the function receiving the mes- 
sage to send back a value without returning. 


Reply Message has no effect if the message was not sent 
through SendMessage. 


lReply is a long integer specifying the result of the message 
processing. The possible values depend on the actual mes- 
sage sent. 


Return Value None. 


PostAppMessage ( h Task, wMsg, wParam, lParam ): bPosted 


Purpose 


Parameters 


Return Value 


This function posts a message to an application identified by 
a task handle and returns without waiting for the applica- 
tion to process the message. The application receiving the 
message obtains the message by calling GetMessage or 
PeekMessage. The hWnd field of the returned MSG struc- 
ture is NULL. 


h Task is the task handle of the application to receive the 
message. 


wMsgq is an unsigned short integer specifying the type of 
message posted. 


wParam is an unsigned short integer specifying additional 
message information. 


[Param is a long integer specifying additional message infor- 
mation. 


bPosted, a Boolean value, is nonzero if the message is posted. 
Otherwise, it is zero. 


Register WindowMessage ( [pString ) : wMsg 


Purpose 


This function defines a new window message that is 
guaranteed to be unique throughout the system. The 
returned message value can be used when calling SendMes- 
sage or PostMessage. 


Register WindowMessage is typically used for communi- 
cation between two cooperating applications. 
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Parameter 


Return Value 


Notes 


If the same message string is registered by two different 
applications, the same message value is returned. The mes- 
sage remains registered until the user ends the Windows ses- 
sion. 


lp String is a long pointer to the message string to be 
registered. 


wMszq is an unsigned short integer in the range C000 to 
FFFF (hexadecimal) if the message is successfully registered. 
wMszq is zero if an error occurs. 


Register Window Message need only be used when the 
same message must be understood by more than one appli- 
cation. For sending private messages within an application, 
an application can use any integer constant in the range 


WM_ USER to BFFF (hexadecimal). 


2.4 Window Function 


The window function is an application-supplied function that processes the 
formatted messages sent to it by Windows or the application’ s main func- 
tion. The window function can have any name (it is called WndProc 
below), but its format and function must be as follows. 


WndProc ( hWnd, wMsg, wParam, lParam ): lReply 


Purpose 


Parameters 


Return Value 
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This routine processes messages sent to it by Windows or 
the application’s main function. 


hWnd is the handle of the window receiving the message. 


wMsg is an unsigned short integer containing the message 
number. 


wParam is an unsigned short integer containing additional 
message-dependent information. 


lParam is a long integer specifying additional message- 
dependent information. 


[Reply is a long integer specifying the result of the message 
processing. The possible return values depend on the actual 
message sent. 


Window Functions 


Note This function must use the Pascal calling conventions, must 
return a long value, and must be declared FAR. 


The [Param parameter often contains two 16-bit values 
instead of a single 32-bit value. You can use the HIWORD 
and LOWORD macros to extract these values. You can 
also use the HIBY TE and LOBYTE macros to extract the 


high- and low-order bytes of a given word. 


2.5 Default Window Function 


The default window function (supplied by Windows) carries out default 
processing of messages. The application-supplied window function 
(described in the previous section) must call the default window function to 
process any messages that it does not process itself. 


DefWindowProc ( hWnd, wMsg, wParam, lParam ) : lReply 


Purpose This function provides default processing for any Windows 
messages that a given application chooses not to process. 


Parameters hWnd is the handle of the window passing the message. 


wMsg is an unsigned short integer specifying the message 
number. 


wParam is an unsigned short integer specifying additional 
message-dependent information. 


{Param is a long integer specifying additional message- 
dependent information. 


Return Value IlReply is a long integer specifying the result of the message 
processing. The possible return values depend on the actual 
message sent. 
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2.6 Window Class Functions 


The RegisterClass function defines and registers window classes to be 
used by an application. Every window created by an application must 
belong to a window class. The window class defines the class attributes of 
the window. 


Any number of window classes can be registered. Once a class has been 
registered, Windows permits the application to create any number of win- 
dows belonging to that class. 


The rest of the functions described in this section retrieve information 
about a window class and set window class attributes. 


RegisterClass ( [pWndClass ) : bRegistered 


Purpose This function registers a window class for subsequent use in 
calls to the Create Window function. The window class 
has the class attributes defined by the contents of the data 
structure pointed to by lpWndClass. The windows created 
with the registered class have a common appearance and 
function. 


Parameters  lpWndClass is a long pointer to a data structure having 
WNDCLASS type. The structure must be filled with the 
appropriate class attributes before being passed to the func- 
tion. 


Return Value bRegtstered, a Boolean value, is nonzero if the class is 
registered. Otherwise, it is zero. 


Notes If two classes having the same name are registered, the most 
recently registered class is recognized; the other is ignored. 


To avoid conflicts with the class names of other applica- 
tions, it is a good idea to use a derivation of the 
application’s module name (from the .DEF file) for the win- 
dow class name. 


GetClassName ( hWnd, IlpClassName, nMazxCount ) : nCopied 


Purpose This function retrieves the class name of the window 
specified by hWnd. 


Parameters hWnd is a handle to the window whose class name is to be 
retrieved. 


lpClassName is a long pointer to a buffer to receive the class 
name. 
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nMazxCount is a short integer specifying the maximum 
number of bytes to be stored in lpClassName. 


Return Value nCopied, a short integer value, is the number of characters 


actually copied to lpClassName. The return value is zero if 
the specified class is not a valid class. 


GetClassWord ( hWnd, nIndez ): word 


Purpose 


Parameter 


Return Value 


Note 


This function retrieves the word at the given n/ndez in the 


WNDCLASS structure of the window specified by hWnd. 
hWnd is a handle to a window. 


nindex must be one of the following short integer values, 
specifying which word of the structure is to be retrieved. 


GCW_ HBRBACKGROUND 
GCW_HCURSOR 

GCW_ HICON 

GCW_ HINSTANCE 

GCW_ CBWNDEXTRA 
GCW_ CBCLSEXTRA 
GCW_STYLE 


word is the value retrieved from the WNDCLASS struc- 
ture. 


To access any extra bytes that were allocated when the win- 
dow class structure was created, use positive offsets as 
indexes, starting at zero for the first byte of the extra space. 


GetClassLong ( hWnd, nIndez ): long 


Purpose 


Parameter 


This function retrieves the long value at the given n/ndez in 
the WNDCLASS structure of the window specified by 
hWnd. 


hWnd is a handle to a window. 


nindex must be one of the following short integer values, 
specifying which long value of the structure is to be 
retrieved. 


GCL_ MENUNAME 
GCL_ WNDPROC 
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Return Value long is the long value retrieved from the WNDCLASS 


Notes 


structure. 


To access any extra bytes that were allocated when the win- 
dow class structure was created, use positive offsets as 
indexes, starting at zero for the first byte of the extra space. 


SetClassWord ( hWnd, nIndez, wNewWord ) : wOldWord 


Purpose 


Parameter 


Return Value 
Note 


This function replaces the word at the given n/ndez in the 


WNDCLASS structure of the window specified by hWnd. 
hWnd is a handle to a window. 


nIndex must be one of the following short integer values, 
specifying which word of the structure is to be changed. 


GCW_ HBRBACKGROUND 
GCW_ HCURSOR 

GCW-_ HICON 

GCW_ HINSTANCE 

GCW_ CBWNDEXTRA 
GCW_ CBCLSEXTRA 
GCW_STYLE 


wNew Word is the replacement value. 
wOld Word is the old value of the specified word. 


The SetClassWord function should be used with great 
care. For example, it is possible to change the background 
color for a class using SetClassWord, but this change does 
not cause all windows belonging to the class to be repainted 
immediately. 


SetClassLong ( hWnd, nIndez, INewLong ): lOldLong 


Purpose 


Parameter 
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This function replaces the long value at the given n/ndez in 
the WNDCLASS structure of the window specified by 
hWnd. 


hWnd is a handle to a window. 


nindezx must be one of the following short integer values, 
specifying which word of the structure is to be changed. 


GCL_ MENUNAME 
GCL_ WNDPROC 


lNewLong is the replacement value. 


Window Functions 


Return Value lOldLong is the old value of the specified long integer. 


Notes Any function set using SetClassLong with the 
GCL WNDPROC index should be exported in the module 
definition file. 


CallWindowProc ( [pPreuWndFunc, hWnd, wMsg, wParam, lParam ) 
: LReply 


Purpose This function passes message information to the function 
specified by [pPreuWndf'unc. CallWindowProc is used for 
window “subclassing.” Normally, all windows with the same 
class share the same window function. A subclass is a win- 
dow or set of windows belonging to the same window class 
whose messages are intercepted and processed by another 
function (or functions) before being passed to the class win- 
dow function. 


To create the subclass, the Set WindowLong function is 
used to change the window function associated with a par- 
ticular window, causing Windows to call the new window 
function instead of the previous one. Any messages not pro- 
cessed by the new window function must be passed to the 
previous window function by calling CallWindowProc. 
This allows a chain of window functions to be created. 


Parameters  IlpPrevWndF unc is a long pointer to the previous window 
function. 


hWnd is the window handle of the window passing the mes- 
sage. 


wMsg is an unsigned integer specifying the message number. 


wParam is an unsigned integer specifying additional 
message-dependent information. 


{Param is an unsigned integer specifying additional 
message-dependent information. 


Return Value (Reply is a long integer specifying the result of the message 
processing. The possible return values depend on the actual 
message sent. 
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2.7 Window Creation Functions 


This section describes the functions used to create, destroy, modify, and 
obtain information about tiled, popup, and child windows. An application 
creates a window by providing all the data needed by Windows to draw the 
image of the window on the display screen. When the application no longer 
needs the window, the window is destroyed and its data are removed from 
memory. 


Create Window ( [pClassName, lp WindowName, dwStyle, X, Y, nWidth, 
nHetght, hWndParent, hMenu, hInstance, lpParam ): hWnd 


Purpose This function creates tiled, popup, and child windows. 


Parameters  IpClassName is a long pointer to a null-terminated ASCII 
string naming the window class. 


lp WindowName is a long pointer to a null-terminated ASCII 
string representing the window name. For windows with 
caption bars, the window name is displayed as the caption. 
When using Create Window to create controls such as but- 
tons, check boxes, and text controls, lp WindowName 
specifies the text of the control. 


dwStyle is a long unsigned integer specifying the style of 
window being created. It can be any combination of the 
styles given in Table 2.1. The control styles given in 
Chapter 6, Table 6.2, can also be used. Styles can be com- 
bined using the bitwise OR operator. 


X and Y are short integer values specifying the initial posi- 
tion of the window. The meaning depends on the window 
style: 


Style Meaning 


Tiled windows X is ignored. If the WS_ VISIBLE 
style is specified, then the Y param- 
eter is assumed to be a Show Win- 
dow command 

SHOW_ICONWINDOW, 

HOW_ OPENWINDOW, 
SHOW_ FULLSCREEN, or 
SHOW_ OPENNOACTIVATE). 
This parameter can be the same as 
the nCmdShow parameter passed to 
the WinMain function. 
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Popup windows 


Child windows 


Window Functions 


X and Y specify (in screen coordi- 
nates) the location of the upper left 
corner of the popup window. For list 
boxes only, X and Y specify the 
location of the upper left corner of 
the window’s client area. 


X and Y specify the location of the 
upper left corner of the child win- 
dow in the client coordinates of the 
parent window (relative to the top 
left corner of the parent’s client 
area). For list boxes only, X and Y 
specify the location of the upper left 
corner of the window’s client area. 


nWidth and nHerght are short integer values specifying the 
size of the window. The meaning depends on the window 


style: 
Style 


Tiled windows 


Popup windows 


Child windows 


Meaning 


nHeight and nWidth are ignored for 
tiled windows. To reflect this fact, it 
is recommended that these parame- 
ters be set to zero. 


nWidth and nHeight specify (in 
device units) the width and height 
of the popup window. For list boxes 
only, nWidth and nHetght specify (in 
device units) the width and height 
of the window’s client area. 


nWidth and nHetght specify (in 
device units) the width and height 
of the child window. For list boxes 
only, nWidth and nHetght specify (in 
device units) the width and height 
of the window’s client area. 


hWndParent is a handle to a parent window. hWndParent 
must be NULL when creating a tiled window. When creat- 
ing a child window, a valid value for hWndParent must be 
given. When creating a popup window, hWndParent can be 
non-null, but does not have to be. 


hMenu is a handle to the menu to be used with the window. 
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Return Value 


Table 2.1 


If hMenu is NULL, the class menu is used. When creating a 
child window, hMenu specifies the child window ID, a short 
integer value. The child window ID is determined by the 
application and should be unique among child windows with 
the same parent. 


hInstance is the instance handle associated with the window 
(passed to the application in the call to WinMain). 


lpParam is a long pointer to a long value that 1s passed to 
the application through the /Param parameter of the 
WM_ CREATE message. 


hWnd is a handle to the new window. It is NULL if the win- 
dow is not created. 


Window Styles 


Style 


WS_ TILED 
WS_ POPUP 


WS-_ CHILD 
WS_ ICONIC 


WS_ BORDER 
WS_ CAPTION 


Meaning 


Create a tiled window. 
Create a popup window. Cannot be used with 


WS-_ CHILD. 


Create a child window. Cannot be used with 


WS_ POPUP. 


Create a window that is initially iconic. For use 


with WS_ TILED only. 
Create a window that has a border. 


Create a window that has a caption bar (implies 


WS_ BORDER). 


WS_ DLGFRAME Create a window with a double border but no 


WS_ SYSMENU 


WS_ SIZEBOX 


WS_ VSCROLL 
WS_ HSCROLL 
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caption. 


Create a window that has a system menu box in 
its caption bar. Used only for windows with 
caption bars. If used with a child window, 
creates a close box instead of a system menu 
box. 


Create a window that has a size box. Used only 
for windows with a caption bar or with vertical 
and horizontal scroll bars. 


Create a window that has a vertical scroll bar. 
Create a window that has a horizontal scroll bar. 


Table 2.1 (continued) 


Style 


WS_ CLIPCHILDREN 


WS_ CLIPSIBLINGS 


WS_ VISIBLE 

WS_ DISABLED 

WS_ TILEDWINDOW 
WS_ POPUPWINDOW 


WS_ CHILDWINDOW 


Window Functions 


Meaning 


Exclude the area occupied by child windows when 
drawing within the parent window. Used when 
creating the parent window. 


Clip child windows relative to each other; that is, 
when a particular child window receives a paint 
message, clip all other overlapping child windows out 
of the region of the child window to be updated. (If 
WS_ CLIPSIBLINGS is not given and child windows 
overlap, it is possible, when drawing in the client area 
of a child window, to draw in the client area of a 
neighboring child window.) For use with WS_ CHILD 


only. 
Create a window that is initially visible. 
Create a window that is initially disabled. 


Create a tiled window having the styles WS_ TILED, 
WS_ CAPTION, WS_ SYSMENU and 
WS_ SIZEBOX. 


Create a popup window that has the styles 
WS_ POPUP, WS_ BORDER, and WS_SYSMENU. 


Create a child window that has the style WS_ CHILD. 


IsWindow ( hWnd ): bEzists 


Purpose This function determines whether the window identified by 
hWnd is a valid, existing window. 


Parameters hWnd is a handle to a window. 


Return Value bEztsts, a Boolean value, is nonzero if hWnd is a valid win- 
dow handle. Otherwise, it is zero. 
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Destroy Window ( hWnd ): bDestroyed 


Purpose This function sends a WM_ DESTROY message to the win- 
dow specified by hWnd and frees any memory that it occu- 
pied. If the window specified by hWnd is the parent of any 
windows (child style or popup style), these windows are 
automatically destroyed when the parent is destroyed. 


Parameters hWnd is a handle to a window. 


Return Value bDestroyed, a Boolean value, is nonzero if the window is 
destroyed. Otherwise, it is zero. 


Get Window Word ( hWnd, nIndez ) : word 


Purpose This function retrieves information about the window 
identified by hWnd. 
Parameter hWnd is a handle to a window. 


nindex must be one of the following integer values, specify- 
ing which word of information is to be retrieved. 


Index Meaning 

GWW_ HINSTANCE Instance handle of the 
module owning the win- 
dow 


GWW_HWNDPARENT Handle of the parent win- 


dow, if any 


GWW_HWNDTEXT Handle to the window’s 
caption 
GWW_ID Control ID of the window 


Return Value word is the short integer value retrieved. 


Notes To access any extra bytes that were allocated when the win- 
dow class structure was created, use positive offsets as 
indexes, starting at zero for the first byte of the extra space. 
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Get WindowLong ( hWnd, nIndez ) : long 


Purpose 


Parameter 


Return Value 
Notes 


This function retrieves information about the window 


identified by hWnd. 
hWnd is a handle to a window. 


nindezx must be one of the following short integer values, 
specifying which long value of information is to be retrieved. 


Index Meaning 

GWL- WNDPROC Long pointer to window 
function 

GWL_STYLE Window style 


long is the long integer value retrieved. 


To access any extra bytes that were allocated when the win- 
dow class structure was created, use positive offsets as 
indexes, starting at zero for the first byte of the extra space. 


Set Window Word ( hWnd, nindez, wNewWord ) : wOldWord 


Purpose 


Parameter 


This function changes an attribute of the window specified 


by hWnd. 
hWnd is a handle to a window. 


nIndex specifies which word of information is to be changed. 


Index Meaning 

GWW_ HINSTANCE Instance handle of the 
module owning the win- 
dow 


GWW_HWNDPARENT Window handle of the 


parent window, if any 


GWW_HWNDTEXT Handle to the window’s 
caption 
GWW_ ID Control ID of the window 


wNewWord is the replacement value. 
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Return Value wOldWord is the old value of the specified word. 


Notes 


To access any extra bytes that were allocated when the win- 
dow class structure was created, use positive offsets as 
indexes, starting at zero for the first byte of the extra space. 


Set WindowLong ( hWnd, nIndex, INewLong ): lOldLong 


Purpose 


Parameters 


This function changes an attribute of the window specified 


by hWnd. 
hWnd is a handle to a window. 


nindex must be one of the following short integer values, 
specifying which long value of information is to be changed. 


Index Meaning 

GWL_ WNDPROC Long pointer to window 
function 

GWL_STYLE Window style 


INewLong is the replacement value. 


Return Value lOldLong is the old value of the specified long integer. 


Notes 


To access any extra bytes that were allocated when the win- 
dow class structure was created, use positive offsets as 
indexes, starting at zero for the first byte of the extra space. 


Any function address set using Set WindowLong with the 
GWL_ WNDPROC index should be created using 
MakeProclInstance. 


2.8 Window Display and Movement Functions 


This section describes functions used to show, hide, and move windows and 
to obtain information about the number and position of windows on the 


screeln. 
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Show Window ( hWnd, nCmdShow ) : bShown 


Purpose This function displays or removes the given window as 


specified by nCmdShow. 
Parameters hWnd is a handle to a window. 


nCmdShow is one of the following short integer values: 
Value Meaning 


HIDE_ WINDOW _ Remove window from screen, but do 
not destroy it. Used for child style 
and popup style windows. 


SHOW_ OPENWINDOW 
Display a previously hidden popup 
or child window, or display a tiled 
window for the first time. 


SHOW_ ICONWINDOW 
Display a previously iconic window. 
Used for tiled windows only. 


SHOW_ FULLSCREEN 
Use the full screen for displaying the 
window. Used for tiled windows 
only. 


SHOW_ OPENNOACTIVATE 
Display the open window, but do 
not activate it. Used for tiled and 
popup windows. 


hWndSwap The window specified by hWnd is 
swapped with the window specified 
by hWndSwap, and the hWndSwap 
window is made iconic. Both hWnd 
and hWndSwap must specify tiled 
windows. 


IconSlot Make the window iconic and use the 
value given by /conSlot to determine 
the position of the icon (where 0 is 
the leftmost position on the icon 
bar). The nine high-order bits of 
IconSlot must be set; the seven low- 
order bits specify the icon position. 
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Column Display the window in the column 
given by Column. The Column 
value must be the result of a bitwise 
OR operation with the desired 
column value and FF40 (hexadeci- 
mal). If Column is FF7F (FF40 and 
3F are used in the OR operation), 
display the window as a new row at 
the bottom of the right-most 
column. If Column is FF7E (FF40 
and 3E are used), display the win- 
dow as a new column to the right of 
the last column. If Column is any 
other value, display the window as a 
new row at the bottom of the given 
column (where column 0 is the left- 
most column). 


Return Value bShown, a Boolean value, is nonzero if the window was previ- 


Notes 


ously visible. It is zero if the window was previously hidden. 


Show Window must only be called once per program with 
the nCmdShow parameter from WinMain. Subsequent calls 
to Show Window must use one of the values listed above 
instead of the nCmdShow parameter. 


Openlcon ( hWnd ) : bOpened 


Purpose 


Parameters 
Return Value 


Notes 
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This function opens the specified window by copying the 
window’s caption and client area to the screen and removing 
its icon from the icon area. 


If other open windows already exist on the screen, Openl- 
con directs Windows to resize and retile those windows to 
make room for the new window. 


hWnd is a handle to a window. 


bOpened, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


This function has the same result as sending a 
WM_SYSCOMMAND message to an iconic window with the 
wParam parameter set to SC_ICON. 


Child style and popup style windows cannot be opened using 
this function. 


Window Functions 


Close Window ( hWnd ): bClosed 


Purpose 


Parameters 


Return Value 


Notes 


This function closes the specified window. If the window is a 
tiled window, it is closed by removing the client area and 
caption of the open window from the display screen and 
moving the window’s icon into the icon area of the screen. 

If the window is a popup window, it is hidden. 


hWnd is a handle to the window to be closed. 


6Closed, a Boolean value, is nonzero if the window is closed. 
Otherwise, it is 0. 


Child windows cannot be closed using this function. Any 
attempt to close a child window is ignored. 


Calling this function has the same effect as a 
WM_SYSCOMMAND message with wParam set to 
SC_ CLOSE. 


Move Window ( hWnd, X, Y, nWidth, nHetght, bRepaint ) 


Purpose 


Parameters 


Return Value 
Notes 


This function causes a WM_SIZE message to be sent to the 
given window. The X, Y, nWidth, and nHetght parameters 
give the new size of the window. 


hWnd is a handle to a popup style or child style window. 


X and Y are short integer values specifying the new coordi- 
nates of the upper left corner of the window. For popup 
style windows, X and Y are in screen coordinates (relative to 
the top left corner of the screen). For child style windows, 
they are in client coordinates (relative to the top left corner 
of the parent window’s client area). 


nWidth and nHezght are short integer values specifying the 
new width and height of the window. 


bRepatnt, a Boolean value, is nonzero if the window is to be 
repainted after moving. If bRepaint is zero, the window does 
not need repainting. | 


None. 


The WM_SIZE message created by this function gives the 
new width and height of the client area of the window, not 
the full window. 
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Bring WindowToTop ( hWnd ) 


Purpose 


Parameters 


This function brings a popup style or child style window to 
the top of a stack of overlapping windows. Bring Win- 
dow ToTop should be used to uncover any window that is 
partially or completely obscured by other, overlapping win- 
dows. 


hWnd is a handle to a popup style or child style window. 


Return Value None. 


SetActiveWindow ( hWnd ): hWndPrev 


Purpose 


Parameters 
Return Value 


Notes 


This function makes a tiled or popup style window the 
active window. If the window specified by hWnd does not 
currently have the input focus, the focus is set to NULL 
(input is ignored). 


hWnd is a handle to the tiled or popup window to be made 
active. 


hWndPrev is a handle to the window that was previously 
active. 


This function should not be called without good reason, 
since it allows an application to take over the active window 
and input focus arbitrarily. Normally, Windows takes care 
of all activation. 


IsWindowVisible ( hWnd ) : bVisible 


Purpose 


Parameters 
Return Value 


Notes 
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This function specifies whether or not the specified window 
is currently visible on the screen. 


hWnd is a handle to a window. 


b Visible, a Boolean value, is nonzero if the given window is 
visible. Otherwise, it is zero. 


Is Window Visible returns nonzero even jf the specified win- 
dow is completely covered by another child style or popup 
style window. 


Window Functions 


AnyPopup ( ): bVisible 


Purpose This function indicates whether or not a popup style window 
is visible on the screen. It searches the entire Windows 
screen, not just the caller’s client area. 


Parameters None. 


Return Value 6Vistble, a Boolean value, is nonzero if a popup style window 
is visible. Otherwise, it is zero. 


IsIconic ( hWnd ): blconic 


Purpose This function specifies whether or not a window is open or 
closed (iconic). 


Parameters hWndisa handle to a window. 

Return Value blIcontc, a Boolean value, is nonzero if the window is closed 
(iconic). It is zero if the window is open. 

EnumWindows ( lpEnumF unc, [Param ): bDone 


Purpose This function enumerates the windows on the screen by 
passing the handle of each window, in turn, to the 
application-supplied function pointed to by IpEnumF unc. 
The window handles are passed in the following order: 

1. Tiled windows 
2. Iconic windows 
3. Popup style windows 


4. Hidden popup style windows 


Child style windows are not enumerated. 


EnumWindows continues to enumerate windows until the 
called function returns zero or until the last window has 
been enumerated. 


Parameters  IlpEnumF unc is a long pointer to the application-supplied 
enumeration function. 


{Param is a long integer that is passed to the enumeration 
function for the application’s use. 


Return Value b6Done, a Boolean value, is nonzero if all windows have been 
enumerated. Otherwise, it is zero. 
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Notes 


The address passed as the lpHnumF unc parameter must be 
created using MakeProclnstance. 


The enumeration function must use the Pascal calling con- 
vention and must be declared FAR. Its form is as follows: 


functionname(hWnd, lParam) 


hWnd is the window handle and [Param is the long parame- 
ter passed to the EnumWindows function. The function 
returns a Boolean value: nonzero to continue enumeration, 
zero to terminate it. 


EnumChild Windows ( hWndParent, lpEnumFunc, lParam ) : bDone 


Parameters 


Return Value 


Notes 
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This function enumerates the child style windows belonging 
to the specified parent by passing the handle of each child 
style window, in turn, to the application-supplied function 
pointed to by lpHnumF unc. 


EnumChild Windows continues to enumerate windows 
until the called function returns zero or until the last child 
style window has been enumerated. 


hWndParent is a handle to the parent window whose child 
windows are to be enumerated. 


lpEnumlunc is a long pointer to the application-supplied 
enumeration function. 


lParam is a long integer that is passed to the enumeration 
function for the application’s use. 


bDone, a Boolean value, is nonzero if all child windows have 
been enumerated. Otherwise, it 1s zero. 


This function does not enumerate popup style windows 
belonging to hwndParent. 


The address passed as the [pEnumI'unc parameter must be 
created using MakeProclInstance. 


The enumeration function must use the Pascal calling con- 
vention and must be declared FAR. Its form is as follows: 


functionname(hWnd, lParam) 


hWnd is the window handle and lParam is the long parame- 
ter passed to the EnumChild Windows function. The 
function returns a Boolean value: nonzero to continue 
enumeration, zero to terminate it. 


Window Functions 


2.9 Dialog Box Functions 


This section describes the functions used to create, access, modify, and 
destroy dialog boxes. A dialog box is a window belonging to a predefined 
window class. Dialog boxes provide a convenient way to interact with the 
user temporarily when input through a menu is not sufficient. 


CreateDialog ( h/nstance, lp TemplateName, hWndParent, lpDialogF unc ) 
: ADIg 


Purpose This function creates a modeless dialog box. The dialog tem- 
plate given by lp TemplateName defines the attributes of the 
dialog box, such as the caption, menu, and controls. 
hWndParent identifies the application window that owns the 
dialog box. The dialog function pointed to by [pDialogF'unc 
processes any messages received by the dialog box. 


CreateDialog returns immediately after creating the dialog 
box. It does not wait for the dialog box to begin processing 
input. 


Parameters hinstance is the instance handle of the module whose execut- 
able file contains the dialog template. 


lo TemplateName is a long pointer to a character string nam- 
ing the dialog template. The string must be a null- 
terminated ASCII string. 


hWndParent is a handle to the window owning the dialog 
box. 


lpDialogk unc is a long pointer to the dialog box function. 


Return Value hADlg is a handle to the newly-created dialog box. It is NULL 
if the dialog box cannot be created. 


Notes The address to be passed as the [pDialogF'unc parameter 
must be created using MakeProclInstance. 


The dialog function must use the Pascal calling convention 
and must be declared FAR. Its form is as follows: 


functionname (hWnd, wMsg, wParam, |Param) 


The dialog function returns a Boolean value that is nonzero 
if the function processes the message, zero if it doesn’t. The 
parameters are identical to WndProc parameters. The 
hWnd parameter contains the window handle of the dialog 
box. 
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IsDialogMessage ( ADIg, lpMsg ) : bUsed 


Purpose 


Parameters 


Return Value 


Notes 


This function determines whether the given message is 
intended for the modeless dialog box specified by hDlg. If 
so, the message is processed and the function returns 
nonzero. 


hDlg is a handle to a dialog box. 
lpMsgq is a long pointer to a MSG data structure. 


6bUsed, a Boolean value, is nonzero if the message has been 
processed, zero otherwise. 


If IsDialogMessage returns nonzero, the message has 
already been processed and should NOT be passed on to 
TranslateMessage or to DispatchMessage. 


The IsDialogMessage can be used with any window con- 
taining controls (not just dialog box windows), if the appli- 
cation wants user actions in the window (such as tabbing or 
pressing the space bar) to have the same effect as in a mode- 
less dialog box. 


DialogBox ( Alnstance, lpTemplateName, hWndParent, lpDialogF unc ) 


Purpose 


Parameters 


: nResult 


This function creates a modal dialog box. The dialog tem- 
plate given by lp TemplateName defines the attributes of the 
dialog box, such as the caption, menu, and controls. 
hWndParent identifies the application window that owns the 
dialog box. The dialog function pointed to by [pDialogFunc 
processes any messages received by the dialog box. 


hInstance is the instance handle of the module whose execut- 
able file contains the dialog template. 


lp TemplateName is a long pointer to a character string nam- 
ing the dialog template. The string must be a null- 
terminated ASCII string. 


hWndParent is a handle to the window owning the dialog 
box. 


lpDtalogF'unc is a long pointer to the dialog box function. 


Return Value nftesult is the short integer value returned by the 
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application’s dialog function. nResult is —1 if insufficient 
memory is available to create the dialog box. 


Notes 


Window Functions 


To create a second dialog box within the dialog function of 
another dialog box while the first dialog box still exists, pass 
the handle of the first dialog box into the second call to 
DialogBox as the parent window handle parameter. The 
first dialog box will be disabled while the second one receives 
input. Similarly, if a message box is created within the dia- 
log function, pass the dialog box handle to the MessageBox 
function as the parent window handle parameter. 


The address to be passed as the [pDialogF'unc parameter 
must be created using MakeProcInstance. 


The dialog function must use the Pascal calling convention 
and must be declared FAR. Its form is as follows: 


functionname (hWnd, wMsg, wParam, |Param) 


The dialog function returns a Boolean value that is nonzero 
if the function processes the message, zero if it doesn’t. The 
parameters are identical to WndProc parameters. The 
hWnd parameter contains the window handle of the dialog 
box. 


EndDialog ( ADIg, nResult ) 


Purpose 


Parameters 


Return Value 
Notes 


This function frees resources and destroys windows associ- 
ated with a modal dialog box. EndDialog is required to 
complete processing whenever the DialogBox function is 
used to create a dialog box. 


hDlg is a handle to a dialog box. 


nfesult, a short integer value, is the value returned by the 
initiating DialogBox call. 


None. 


If necessary, EndDialog can be called during the processing 
of the WM_INITDIALOG message. | 


DigDirList ( hDlg, lpPathSpec, nIDListBoz, nIDStaticPath, wFiletype ) 


Purpose 


: bListed 


This function creates a list that allows the user to select files 
or directories. 


DigDirList fills the list box specified by nIDListBoz with 
the names of all files matching the path specification given 
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Parameters 
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by [pPathSpec. Subdirectories are enclosed in square brack- 
ets; drives are shown in the form |-z-], where zis the drive 
letter. 


If lpPathSpec includes a drive and/or directory specification, 
the current drive and directory are changed to the desig- 
nated drive and directory before the list box is filled. The 
text control identified by nJDStaticPath is also updated with 
the new drive and/or directory specification. 


After the list box is filled, lpPathSpec is updated by remov- 
ing the drive and/or directory portion of the path 
specification. 


hDlg is the dialog box window handle. 
lpPathSpec is a long pointer to a path specification string. 


nlDListBoz is the ID of a list box control. If nJDLtstBorz is 0, 
DlgDirList assumes no list box exists and does not attempt 
to fill it. 


nlDStaticPath is the ID of a static text control used for 
displaying the current drive and directory. If nJDStaticPath 
is 0, DigDirList assumes that no such text control is 
present. 


wk tletype is an unsigned integer whose bits specify MS- 
DOS™ file attributes. w'tletype should be O for normal files 
(files with none of the attributes listed below), and should be 
set as shown below for other files. 


Bit (hexadecimal) Meaning 


01 Read only file 
02 Hidden file 
04 System file 

10 Subdirectory 
20 Archive 

4000 Drive bit 
8000 Exclusive bit 


If the “exclusive bit” is set, only files of the specified type 
are listed. Otherwise, files of the specified type are listed in 
addition to normal files. 


Window Functions 


Return Value 6bListed is nonzero if a listing was made, even an empty list- 
ing. A zero return value implies that the input string did 
not contain a valid search specification. 


DigDirSelect ( ADlg, lpString, nIDListBoz ): bDirectory 


Purpose This function gets the current selection from a list box built 
by DlgDirList and copies the selection to the location 
specified by lpString. 


If the current selection is a directory name or drive letter, 
DigDirSelect removes the enclosing square brackets (and 
hyphens, for drive letters) so that the name or letter is ready 
to be inserted into a new path specification. 


Parameters hDigis a handle to a dialog box. 


lpString is a long pointer to a string buffer to store the selec- 
tion. 


nIDListBoz is the ID of a list box control in the dialog box. 


Return Value bDutrectory, a Boolean value, is nonzero is the current selec- 
tion is a directory name. Otherwise, it is zero. 


GetDlgItem ( ADIg, nJDDigItem ) : hCtl 


Purpose This function retrieves the handle of a dialog item (control) 
from the dialog box specilied by ADlg. 


Parameters hDligis a handle to a dialog box. 
nIDDiglItem is the integer nID of the item to be retrieved. 
Return Value hCtlis a handle to the given dialog item. It is NULL if no 
item with the given n/DDlig/tem exists. 
SetDlgItemInt ( hDlg, nJDDigitem, wValue, bSigned ) 


Purpose This function sets the text of a dialog item (control) to the 
string representation of an integer value. 


Parameters hDlgis a handle to a dialog box. 


nIDDigltem is an integer value identifying the dialog item to 
be modified. 


w Value is the unsigned short integer value to be set. 
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bSitgned specifies whether or not the integer value is signed. 
If bStgned is nonzero, wValue is a signed integer; if zero, 
w Value is unsigned. 


Return Value None. 


GetDlgItemInt ( ADIg, nJDDigltem, lp Translated, bSigned ) : wValue 


Purpose 


Parameters 


This function translates the text of a dialog item into an 
integer value. 


hDig is a handle to the dialog box. 
nIDDigItem identifies the dialog item to be translated. 


ly Translated is a long pointer to a Boolean variable. 
GetDlgItemInt places a nonzero value in the location 
pointed to by [p Translated if the text is translated without 
errors. It places zero if any non-numeric characters occur in 
the text, or if the number represented by the text is too 
large to fit into an integer. If lp Translated is NULL, the 
GetDlgItemInt does not warn about errors. 


bStgned is a Boolean value specifying whether or not the 
value to be retrieved is signed. If 6Stgned is nonzero, 
GetDlgItemInt checks for a minus sign (—) before translat- 
ing the number. Otherwise, GetDlgItemInt does not check 
for a minus sign. 


Return Value wValue is an integer value specifying the translated value of 


the dialog item text. Since 0 is a valid return value, 
lp Translated must be used to detect errors. 


SetDigItemText ( hDig, nIDDigItem, lpString ) 


Purpose 


Parameters 


This function sets the caption or text of a dialog item (con- 
trol) in the dialog box specified by ADlg. 


hDlig is a handle to the dialog box. 
nIDDiglItem is an integer value identifying the control item. 


lpString is a long pointer to a null-terminated string 
representing the new caption or text. 


Return Value None. 
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GetDigItemText ( ADig, nIDDigItem, lpString, nMaxCount ) : nCopied 


Purpose 


Parameters 


This function retrieves the caption or text associated with a 
dialog item (control) and copies it to the location pointed to 
by l[pString. 


hDlg is a handle to the dialog box. 


niDDlgltem is an integer value identifying the dialog item 
whose caption or text is to be retrieved. 


lpString is a long pointer to the buffer to receive the text. 


nMazCount is a short integer value specifying the maximum 
length in bytes of the string to be copied to I[pString. If the 
string is longer than nMazCount, it is truncated. 


Return Value nCopted is a short integer value specifying the number of 


characters copied to the buffer. nCopied is 0 if no text is 
copied. 


CheckDlgButton ( ADlg, nJDButton, wCheck ) 


Purpose 


Parameters 


This function places or removes a checkmark next to a but- 
ton control, or changes the state of a 3-state button. 


hDig is a handle to the dialog box. 


nlDButton is a short integer value specifying the button con- 
trol to be modified. 


wCheck is a short unsigned integer value specifying the 
action to take. If wCheck is nonzero, the CheckDlgButton 
places a checkmark next to the button; if zero, the check- 
mark (if any) is removed. For 3-state buttons, if wCheck is 
2, the button is grayed; if wCheck is 1, it is checked; and if 
wCheck is zero, the checkmark (if any) is removed. 


Return Value None. 


IsDlgButtonChecked ( hDlg, nIDButton ) : wCheck 


Purpose 


Parameters 


This function determines whether a button control has a 
checkmark next to it, or whether a 3-state button control is 
grayed, checked, or neither. 


hDig is a handle to the dialog box. 
nlDButton is the integer ID of the button control. 
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Return Value wCheck is nonzero if the given control has a checkmark, zero 
if it does not. For 3-state buttons, wCheck is 2 if the button 
is grayed, 1 if the button has a checkmark next to it, and 
zero otherwise. 


CheckRadioButton ( hDig, n/DFirstButton, nIDLastButton, 
nIDCheckButton ) 


Purpose This function checks the radio button specified by nJD- 
CheckButton and unchecks all other radio buttons in the 
group of buttons specified by n/DFirstButton and n/DLast- 
Button. 


Parameters hDlgis a handle to the dialog box. 


nlDFirstButton and nIDLastButton are integer [D values for 
the first and last radio buttons in the group. The ID 


numbers of the radio buttons in the group must be sequen- 
tial. 


nIDCheckButton is an integer ID value identifying the radio 
button to be checked. 


Return Value None. 
SendDlgItemMessage ( hDlg, nJDDigItem, wMsg, wParam, [Param ) 
: lResult 


Purpose This function sends a message to the dialog item (control) 
identified by nJDDIg/item within the dialog box specified by 
hDig. SendDligIltemMessage does not return until the 
message has been processed. 


Parameters hDlgis a handle to the dialog box. 


nIDDlgitem is the integer ID value of the dialog item to 
receive the message. 


wMsgq is an unsigned short integer value representing a mes- 
sage. ‘ 


wParam is a short integer value specifying additional mes- 
sage information. 


‘Param is a long integer value specifying additional message 
information. 


Return Value (Result, a long integer, is equal to the value returned by the 
dialog item’s window function. 
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MapDialogRect ( ADIg, lpRect ) 


Purpose This function converts the dialog box coordinates given in 
lpRect to client coordinates. 


Parameters hDlg isa handle to a dialog box. 


lpRect is a long pointer to a data structure with RECT 
type that contains the dialog box coordinates to be con- 
verted. The dialog box coordinates in [pfect are replaced 
with the client coordinates. 


Return Value None. 


2.10 Clipboard Functions 


This section describes the clipboard functions used to carry out data inter- 
change between Windows applications. The clipboard provides a way for 
applications to pass data handles to other applications. 


The clipboard recognizes five predefined data formats and allows applica- 
tions to define additional formats. The predefined formats are text format, 
bitmap format, Microsoft Symbolic Link format (SYLK), Software Arts’ 
Data Interchange Format (DIF), and metafile picture format. 


OpenClipboard ( hWnd): bOpened 


Purpose This function opens the clipboard for examination and 
prevents other applications from modifying the clipboard 
contents. 


Parameters hWnd is a handle to the window to be associated with the 
open clipboard. 


Return Value bOpened, a Boolean value, is nonzero if the clipboard is 
opened. If the clipboard has already been opened by 
another application, OpenClipboard returns zero. 


CloseClipboard ( }: bClosed 


Purpose This function closes the clipboard. CloseClipboard should 
be called when a window has finished examining or changing 
the clipboard. It lets other applications access the clip- 
board. 
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Parameters 


None. 


Return Value 6Closed, a Boolean value, is nonzero if the clipboard is 


closed. Otherwise, it is zero. 


EmptyClipboard ( ): bEmptted 


Purpose 


Parameters 
Return Value 


Note 


This function empties the clipboard and frees handles to 
data in the clipboard. It then assigns ownership of the clip- 
board to the window that currently has the clipboard open. 


None. 


bEmptied, a Boolean value, is nonzero if the clipboard is 
emptied. It is zero if an error occurs. 


The clipboard must be open when Empty Clipboard is 
called. 


GetClipboardOwner ( ): hWnd 


Purpose 


Parameters 


This function retrieves the window handle of the current 
owner of the clipboard. 


None. 


Return Value hWnd is a handle to the window that owns the clipboard. It 


Note 


is NULL if the clipboard is not owned. 


The clipboard can still contain data even if the clipboard is 
not currently owned. 


SetClipboardData ( wFormat, hMem ): hClipData 


Purpose 


Parameters 
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This function sets a data handle into the clipboard for the 
data specified by hMem. The data are assumed to have the 
format specified by wFormat. 


After a clipboard data handle has been assigned, SetClip- 
boardData frees the block identified by hMem. 


wFormat is an unsigned short integer value that specifies a 
data format. It can be any one of the following predefined 
formats: 


Format 


CF_ TEXT 


CF_ BITMAP 


CF_ METAFILEPICT 


CF_SYLK 


CF_ DIF 


CF_ OWNERDISPLAY 


CF_ DSPTEXT 


CF_ DSPBITMAP 


Window Functions 


Meaning 


Text format. Hach line ends 
with a carriage return/linefeed 
CR-LF) combination. A 

ULL character signals the 
end of the data. 


Bitmap as defined by the BIT- 
MAP data structure. 


Metafile picture as defined by 
the METAFILEPICT data 


structure. 


Microsoft’s Symbolic Link for- 
mat. 


Software Arts’ Data Inter- 
change Format. 


Owner display format. The 
clipboard owner is responsible 
for displaying and updating 
the clipboard application win- 
dow, and will receive 

WM_ PAINTCLIPBOARD, 
WM_SIZECLIPBOARD, 
WM_ VSCROLLCLIPBOARD, 
WM_ HSCROLLCLIPBOARD, 


and 
WM_ ASKCBFORMATNAME 
messages. The hMem parame- 


ter must be NULL. 


Text display format associated 
with private format. hMem 
must be a handle to data that 
can be-displayed in text format 
in lieu of the privately format- 
ted data. 


Bitmap display format associ- 
ated with private format. 
hMem must be a handle to 
data that can be displayed in 
bitmap format in lieu of the 
privately formatted data. 
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CF_ DSPMETAFILEPICT 
Metafile picture display format 
associated with private format. 
hMem must be a handle to 
data that can be displayed in 
metafile picture format in lieu 
of the privately formatted 
data. 


CF_PRIVATEFIRST Range of integer values that 
can be used for private for- 
mats. Data handles associated 
with formats in this range will 
not be freed automatically; 
hMem must be freed by the 
application before the applica- 
tion terminates or when a 
WM_ DESTROYCLIPBOARD 


message is received. 


CF_ GDIOBJFIRST Range of integer values used 
for private formats where 
hMem is assumed to be a han- 
dle to a GDI object. Data han- 
dles associated with formats in 
this range are automatically 
freed by Windows (using 
DeleteObject) when the 
application terminates or the 
clipboard is emptied. 


In addition to the above predefined formats, any format 
value registered through RegisterClipboardFormat can 
be used as the wh ormat parameter. 


hMem is a global handle to data in the specified format. 
hMem can be NULL; in this case, the application does not 
have to format the data and provide a handle to it until 
requested to do so through a WM_ RENDERFORMAT mes- 


sage. 


Return Value AClipData is the data handle assigned by the clipboard. 


Note 
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Once hMem has been passed to SetClipboardData, the 
block of data becomes the property of the clipboard. The 
application may read the data using hCltpData, but should 
not free the block or leave it locked. 


Window Functions 


GetClipboardData ( wlormat ): hClipData 


This function retrieves data from the clipboard in the for- 
mat given by wkormat. The clipboard must have been pre- 


Purpose 


Parameters 


viously opened. 


wF'ormat is an unsigned short integer value that specifies a 
data format. It can be any one of the following predefined 


formats: 
Format 


CF_ TEXT 


CF_ BITMAP 


CF_ METAFILEPICT 


CF_SYLK 


CF_ DIF 


CF_ OWNERDISPLAY 


CF_ DSPTEXT 


CF_ DSPBITMAP 


Meaning 


Text format. Each line ends 
with a carriage return/linefeed 
CR-LF) combination. A 

ULL character signals the 
end of the data. 


Bitmap as defined by the BIT- 
MAP data structure. 


Metafile picture as defined by 
the METAFILEPICT data 


structure. 


Microsoft’s Symbolic Link for- 
mat. 


Software Arts’ Data Inter- 
change Format. 


Owner display format (can be 
used only by the clipboard 
owner). 


Text display format associated 
with private format. 


Bitmap display format associ- 
ated with private format. 


CF_ DSPMETAFILEPICT 


Metafile picture display format 
associated with private format. 
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CF_PRIVATEFIRST Range of integer values that 
can be used for private for- 
mats. Data handles associated 
with formats in this range will 
not be freed automatically; 
hMem must be freed by the 
application before the applica- 
tion terminates or when a 
WM_ DESTROYCLIPBOARD 


message is received. 


CF_ GDIOBJFIRST Range of integer values used 
for private formats where 
hMem is assumed to be a han- 
dle to a GDI object. Data han- 
dles associated with formats in 
this range are automatically 
freed by Windows (using 
DeleteObject) when the 
application terminates or the 
clipboard is emptied. 


In addition to the above predefined formats, any format 
value registered through RegisterClipboardFormat can 
be used as the w/ormat parameter. 


Return Value AClipData is a handle to the data retrieved from the clip- 
board. It is NULL if there is an error. 


Notes The available formats can be enumerated in advance by 
using EnumClipboardFormats. 


The data handle returned by GetClipboardData is con- 
trolled by the clipboard, not the application. Thus, the 
application should copy the data immediately instead of 
relying on the data handle for long-term use. The applica- 
tion should not free the data handle or leave it locked. 


RegisterClipboardFormat ( [pFormatName ) : wFormat 


Purpose This function registers a new clipboard format whose name 
is pointed to by lpFormatName. The registered format can 
be used in subsequent clipboard functions as a valid format 
in which to render data, and it will appear in the clipboard’s 
list of formats. 
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Parameters 


Return Value 


Note 


Window Functions 


lpFormatName is a long pointer to a character string naming 
the new format. The string must be a null-terminated 


ASCII string. 


wFormat is an unsigned short integer value specifying the 
newly registered format. If the identical format name has 
been registered before, even by a different application, the 
format’s reference count is incremented and the same value 
is returned as when the format was originally registered. 
wk ormat is 0 if the format cannot be registered. 


The format value returned by Register ClipboardMessage 
is in the range C000 to FFFF (hexadecimal). 


CountClipboardFormats ( ) : nCount 


Purpose 


Parameters 
Return Value 


This function retrieves a count of the number of formats 
that the clipboard can render. 


None. 


nCount is an integer value specifying the number of data for- 
mats in the clipboard. 


EnumClipboardFormats ( wFormat ) : nNertFormat 


Purpose 


Parameters 


Return Value 


This function enumerates the formats found in a list of 
available formats belonging to the clipboard. On each call 
to EnumClipboardFormats, the wlormat parameter 
specifies a known available format, and the function returns 
the format that appears next in the list. The first format in 
the list can be retrieved by setting wkormat to 0. 


wF'ormat is an unsigned short integer value specifying a 
known format. 


nNeztFormat is an integer value specifying the next known 
clipboard data format. It is 0 if wFormat specifies the last 
format in the list of available formats. 


GetClipboardFormatName ( wFormat, lpFormatName, nMazCount ) 


Purpose 


: nCopted 


This function retrieves from the clipboard the name of the 
registered format specified by wKormat. The name is copied 
to the buffer pointed to by lpFormatName. 
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Parameters  wFormatis a unsigned short integer value specifying the 
type of format to be retrieved. It must not specify any of 
the predefined clipboard formats. 


lypFormatName is a long pointer to the buffer to receive the 
format name. 


nMazxCount is an integer value specifying the maximum 
length in bytes of the string to be copied to the buffer. 


Return Value nCopted is an integer value specifying the actual length of 
the string copied to the buffer. It is 0 if the requested for- 
mat does not exist or is a predefined format. 


SetClipboard Viewer ( hWnd ): hWndNezt 


Purpose This function adds the window specified by hWnd to the 
chain of windows that are notified (via the 
WM_ DRAWCLIPBOARD message) whenever the contents 


of the clipboard have changed. 


Parameters hWndisa handle to the window to receive clipboard viewer 
chain messages. 


Return Value hWndNezt is the window handle of next window in the clip- 
board viewer chain. This handle should be saved in static 
memory and used in responding to clipboard viewer chain 
messages. 


Notes Windows that are part of the clipboard viewer chain must 
respond properly to WM_ DESTROY, 
WM_ CHANGECBCHAIN, and WM_ DRAWCLIPBOARD 
messages. See the description of these messages in Chapter 
8 for details. 


If an application wishes to remove itself from the clipboard 
viewer chain, it must call ChangeClipboardChain. 


GetClipboardViewer ( ): hWnd 


Purpose This function retrieves the window handle of the first win- 
dow in the clipboard viewer chain. 


Parameters None. 


Return Value hWnd is a handle to the window currently responsible for 
displaying the clipboard. It is NULL if there is no viewer. 
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ChangeClipboardChain ( hWnd, hWndNezt ) : bRemoved 


Purpose This function removes the window specified by hWnd from 
the chain of clipboard viewers and makes the window 
specified by hWndNezt the descendant of hWnd’s ancestor in 
the chain. 


Parameters hWndisa handle to the window to be removed from the 
chain. The handle must previously have been passed to 
SetClipboardViewer. 


hWndNezt is a handle to the window after hWnd in the clip- 
board viewer chain (the handle returned by SetClipboard- 
Viewer, unless the sequence was changed in response to a 


WM_ CHANGECBCHAIN message. ) 


Return Value bRemoved, a Boolean value, is nonzero if hWnd is found and 
removed. Otherwise, bRemoved is zero. 


2.11 Input Functions 


This section describes the functions used to control input to a given win- 
dow. An application receives input from the system mouse, keyboard, or 
timer. The input functions let an application disable input from these 
devices, take complete control of the devices, or define special actions to 
take when input from a device is received. 


An application must acquire the input focus to receive input. Windows 
directs all keyboard input to the window with the input focus. Only one 
window can have the input focus at any given time. 


The window with the input focus is either the active window (a tiled or 
popup style window) or a child of the active window. For example, a dialog 
box may be the active window, but a child window within the dialog box 
(such as an edit control) may have the focus. 


The mouse capture functions let an application capture all input from the 
system mouse. Normally, an application only receives mouse input when 
the mouse cursor is in its window. 


The timer functions let an application direct a system timer to pass it a 


message after a given amount of time has elapsed, and define a special 
action to take when the message arrives. 
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The input enable functions let an application enable or disable all mouse 
and keyboard input for a given window. 


SetFocus ( hWnd ): hWndPrev 


Purpose 


Parameters 
Return Value 


Notes 


This function assigns the input focus to the window specified 
by hWnd. The input focus directs all subsequent keyboard 
input to the given window. The window, if any, that previ- 
ously had the input focus loses it. If hWnd is NULL, key- 
strokes will be ignored. 


SetFocus sends a WM_KILLFOCUS message to the win- 
dow losing the input focus and a WM_SETFOCUS message 
to the window getting the input focus. It also activates 
either the window that’s receiving the focus or the parent of 
the window receiving the focus. 


hWnd is a handle to the window to receive the keyboard 
input. 


hWndPrev is a handle to the window that had the input 
focus. It is NULL if there is no such window. 


If a window is active but it doesn’t have the focus (so no 
window has the focus), any key pressed will produce a 
WM_SYSKEYUP, SYSKEYDOWN, or 
WM_SYSCHAR message. If the VK_ MENU key is also 
pressed, the [Param parameter of the message will have bit 
20000000 (hexadecimal) set. Otherwise, the messages that 
are produced do NOT have this bit set. 


GetFocus ( ): hWnd 


Purpose 


Parameters 
Return Value 


This function retrieves the handle of the window currently 
owning the input focus. 


None. 


hWnd is a window handle if the ame is successful. Oth- 
erwise, it is NULL. 


GetKeyState ( nViriKey ) : nState 


Purpose 
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This function retrieves the state of the virtual key specified 
by nVirtKey. The state specifies whether the key is up, 
down, or toggled. 


Parameters 


Window Functions 


nVirtKey is an integer value specifying a virtual key. If the 
desired virtual key is a letter or digit ( “A” through “Z,” “a” 
through “z,” or “0” through “9”), nVirtKey must be set to 
the ASCII value of that character. For other keys, it must 
be one of the values given in Table 2.2. 


Return Value nState is an integer value specifying the state of the given 


Table 2.2 
Virtual Keys 


virtual key. If the high-order bit is 1, the key is down. Oth- 
erwise, it is up. If the low-order bit is 1, the key is toggled. 
A toggle key, such as “Caps-Lock,” is toggled if it has been 
pressed an odd number of times since the system was 
started. The key is untoggled if the low bit is 0. 


Key Meaning 
VK_LBUTTON Left mouse button 
VK_ RBUTTON Right mouse button 
VK_ MBUTTON Middle mouse button 
VK_ BACK Backspace key 

VK_ TAB Tab key 

VK_ RETURN Return key 

VK_ SHIFT Shift key 

VK_ CONTROL Control (CTRL) key 
VK_ MENU Alternate (ALT) key 
VK_ CAPITAL Caps Lock key 

VK_ INSERT Insert key 

VK_ DELETE Delete key 

VK_ CLEAR Clear key 

VK_ ESCAPE Escape (ESC) key 
VK_ HELP Help key 

VK_ NUMPADO Numeric keypad 0 
VK_ NUMPAD1 Numeric keypad 1 
VK_ NUMPAD2 Numeric keypad 2 
VK_ NUMPAD3 Numeric keypad 3 
VK_ NUMPAD4 Numeric keypad 4 
VK NUMPAD5 Numeric keypad 5 
VK_ NUMPAD6 Numeric keypad 6 
VK_ NUMPAD7 Numeric keypad 7 
VK_ NUMPAD8 Numeric keypad 8 
VK_ NUMPADS9 Numeric keypad 9 
VK_ MULTIPLY Multiply key 

VK_ ADD Add key 
VK_SEPARATOR _ Separator key 

VK_ SUBTRACT Subtract key 

VK_ DECIMAL Decimal point key 
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Key Meaning 


VK_ DIVIDE Divide key 

VK_ SPACE Spacebar 

VK_ PRIOR Prior Screen key 
VK_ NEXT Next Screen key 
VK_ END End of document key 
VK_ HOME Home key 

VK_ CANCEL Cancel key 

VK_ PAUSE Pause key 

VK_ LEFT Left arrow key 
VK_ UP Up arrow key 
VK_ RIGHT Right arrow key 
VK_ DOWN Down arrow key 
VK_ SELECT Select key 

VK_ PRINT Print key 


VK_F1 Function 1 key 
VK_F2 Function 2 key 
VK_F3 Function 3 key 
VK_F4 Function 4 key 
VK_F5 Function 5 key 
VK_ F6 Function 6 key 
VK_F7 Function 7 key 
VK_F8 Function 8 key 
VK_F9 Function 9 key 
VK_F10 Function 10 key 
VK_F11 Function 11 key 
VK_ F12 Function 12 key 
VK_F13 Function 13 key 
VK_F14 Function 14 key 
VK_F15 Function 15 key 
VK_ F16 Function 16 key 


SetCapture ( hWnd ) : hWndPrev 


Purpose This function causes all subsequent mouse input to be sent 
to the window given by hWnd, regardless of the position of 
the mouse cursor. 


Parameters hWnd is a handle to the window to receive the mouse input. 


Return Value hWndPrev is the handle of the window that receives all 
mouse input prior to the SetCapture call. It is NULL if 
there is no such window. 
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ReleaseCapture ( ) 


Purpose 


Parameters 


This function releases mouse input and restores normal 
input processing. 


None. 


Return Value None. 


SetTimer ( AWnd, nIDEvent, wElapse, lpTimerFunc ) : nIDNewEvent 


Purpose 


Parameters 


Return Value 


Notes 


This function creates a system timer event identified by 
nIDEvent. When a timer event occurs, Windows passes a 
WM_ TIMER message to the user-supplied function specified 
by lpTimerFunc. The function can then process the event. 
A NULL value for lp TimerF'unc causes WM_ TIMER mes- 
sages to be placed in the application queue. 


hWnd is a handle to a window. 


nlDEvent is an integer value identifying the timer event. If 
hWnd is NULL, the nJDEvent parameter is ignored. Instead, 
SetTimer returns a unique ID that can be used later with 


KillTimer. 


wHlapse is an unsigned short integer value specifying the 
elapsed time in milliseconds between timer events. 


lp TimerF unc is a long pointer to the function to be notified 
when the timer event takes place. If lp TimerF'unc is NULL, 
the WM_ TIMER message is placed in the application queue; 
the hwnd member of the MSG structure contains the hWnd 
parameter given in the Set Timer call. 


nIDNewkKvent is an integer value specifying the new timer 
event. If hWndis NULL, SetTimer returns a unique ID. If 
hWnd is not NULL, the return value is the same as the 
nlDEvent parameter. The return value is 0 if the timer event 
is not set. 


The lpTtmerF'unc function must have the form: 
functionname (hWnd, wMsg, nIDEvent, dwTime) 


where hWnd is a handle to the window associated with the 
timer event, wMsg is the WM_ TIMER message, n/DEvent is 
a short integer value specifying the timer’s ID, and dw7ime 
is a long unsigned integer specifying the current system 
time. The function can carry out any desired tasks. 
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KillTimer ( hWnd, nIDEvent ): bKilled 


Purpose 


Parameters 


Return Value 


This function kills the timer event identified by hWnd and 
nlDEvent. Any pending WM_ TIMER messages associated 
with the timer are removed from the message queue. 


hWnd is the handle of the window associated with the given 
timer event. 


nlDEvent is an integer value identifying the timer event to 
be killed. This must be a valid event ID returned by 
SetTimer or 0. If it is 0, KillTimer removes an arbitrary 
timer event. 


bKaulled, a Boolean value, is nonzero if the event is killed. It 
is zero if it cannot find the specified timer event. 


Enable Window ( hWnd, bEnable ) : bDone 


Purpose 


Parameters 


Return Value 


Notes 
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This function enables and disables mouse and keyboard 
input to the specified window. When input is disabled, 
input such as mouse clicks and key presses are ignored by 
the window. When enabled, all input is processed. 


Enable Window enables mouse and keyboard input to a 
window if bEnable is nonzero and disables it if bEnable is 
zero. 


hWnd is a handle to a window. 


bE nable is a Boolean value specifying whether or not the 
given window is to be enabled for input. 


bDone, a Boolean value, is nonzero if the window is enabled 
or disabled as specified. It is zero if an error occurs. 


A window must be enabled before it can be activated. For 
example, if an application is displaying a modeless dialog 
box and has disabled its main window, the main window 
must be enabled before the dialog box is destroyed. Other- 
wise, another window (or no window, if there are not other 
windows) will get the input focus and be activated. 


If a child window is disabled, it is ignored when Windows 
tries to determine which window should get mouse mes- 
sages. 


Initially, all windows are enabled by default. Enable Win- 
dow must be used to disable a window explicitly. 


Window Functions 


IsWindowEnabled ( hWnd ): bEnabled 


Purpose This function specifies whether or not the specified window 
is enabled for mouse and keyboard input. 


Parameters hWnd is a handle to a window. 


Return Value bEnabled, a Boolean value, is nonzero if the window is 
enabled. Otherwise, it is zero. 


Notes A child window only receives input if it is both enabled and 
visible. 


2.12 Menu Functions 


This section describes the functions used to create, modify, and destroy 
menus. Applications access menus through menu handles, which are 
assigned by Windows. 


Two types of menus can be distinguished: top-level (or “menu bar”) menus, 
and popup menus (also called “drop-down” or “pull-down” menus.) A top- 
level menu consists of menu items displayed in a window’s menu bar. A 
popup menu Is a menu associated with a top-level menu item; when the 
user selects that menu item, the popup menu appears. The popup menu 
has its own unique menu handle (as does each top-level menu). 


Each item on a top-level menu has either a command value or a popup 
menu associated with it. If the item has no popup menu, the command 
value is sent to the application in a WM_COMMAND message. If the item 
has a popup menu, that menu is displayed. If the user selects an item from 
the system menu, the command value for that item is sent in a 


WM_SYSCOMMAND message. 

Individual menu items can be grayed, disabled, enabled, checked, or 
unchecked (except that top-level menu items cannot be checked.) 
SetMenu ( hWnd, hMenu ) : bSet 


Purpose This function sets the given window’s menu to hMenu. If 
hMenu is NULL, the window’s current menu is removed. 
SetMenu causes the window to be redrawn to reflect the 
menu change. 


Parameters hWnd is a handle to the window whose menu is to be 
changed. 


hMenu is a handle to the new menu. 
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Return Value bSet, a Boolean value, is nonzero if the menu is changed. 
Otherwise, it is zero. 


GetMenu ( hWnd ) : hMenu 


Purpose This function retrieves a handle to the menu of the specified 
window. 


Parameters hWnd is a handle to the window whose menu ts to be exam- 
ined. 


Return Value hMenuis a handle to a menu. It is NULL if the given win- 
dow has no menu. 


CreateMenu ( ): hMenu 


Purpose This function creates a menu. The menu is initially empty, 
but can be filled with menu items by using the 
ChangeMenu function. 


Parameters None. 


Return Value hMenuw is a handle to the newly-created menu. It is NULL if 
the menu cannot be created. 


DestroyMenu ( hMenu ): bDestroyed 


Purpose This function destroys the menu specified by hMenu and 
frees any memory that it occupied. 


Parameters hMenuis a handle to the menu to be destroyed. 


Return Value bDestroyed, a Boolean value, is nonzero if the menu is 
destroyed. Otherwise, it is zero. 


ChangeMenu ( hMenu, wlDChangeltem, lpNewltem, wIDNewltem, 
wChange ): bChanged 


Purpose This function appends, inserts, deletes, or modifies a menu 
item in the menu given by hMenu. The wlDChangeltem, 
lpNewltem, wlIDNew/tem, and wChange parameters define 
which item to change and how to change it. 


Parameters hMenuis a handle to the menu to be changed. 


wlDChangeltem is an unsigned short. integer value identify- 
ing the item to be changed. If the MF_ BYPOSITION flag is 
specified, w/[DChangeltem gives the position of the menu 
item to be changed (the first item is at position 0). If 

MF_ BYCOMMAND is specified instead, w/DChangeltem is 


the menu item ID. The menu item ID can specify an sub- 


62 


Return Value 


Notes 


Window Functions 


menu item (that is, an item in a popup menu associated 
with an item of hMenu). If neither flag is given, the default 
is MF_BYCOMMAND. When MF_ INSERT is used, w/D- 
Changeltem identifies the item before which the new item is 
to be inserted. When MF_ APPEND is used, w/D- 
Changeltem is NULL. 


lpNewltem is either a handle to a bitmap (when 

MF_ BITMAP is specified in the wChange parameter), a han- 
dle to a menu (when MF_ POPUP is specified) or a long 
pointer to a character string (when MF_STRING is 
specified). The default is MF_STRING. A NULL value for 
lpNewltem creates a horizontal break (the same effect as 


using the MF_ SEPARATOR flag). 


wlDNewltem is an unsigned short integer value identifying 
the new menu item. If the MF_BYPOSITION flag is 
specified, w/DNewltem gives the position of the new menu 
item (the first item is at position 0). If MF_BYCOMMAND 
is specified instead, w/DNewltem is the new menu item ID. 
If neither flag is given, the default is MF. BYCOMMAND. 
When the MF_ POPUP flag is used, w/DNewltem is a handle 


to the popup menu. 


wChange is an unsigned short integer value specifying how 
to change the menu. It consists of one or more of the values 
given in Table 2.3. These values are combined using the bit- 
wise OR operator. 


bChanged, a Boolean value, is nonzero if the change is suc- 
cessful. Otherwise, it is zero. 


If a top-level menu item is changed (i.e., a menu item 
appearing in the menu bar at the top of an application’s 
window), the DrawMenuBar function should be called to 
redraw the menu bar. 


ChangeMenu is useful for inserting, deleting, changing, 
and appending menu items, and setting the attributes of the 
new or changed items. However, to change the attributes of 
existing menu items, it is much faster to use CheckMenul- 
tem and EnableMenultem. 
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Table 2.3 


ChangeMenu Flags 


Flag 


MF_ CHANGE 
MF'_ INSERT 

MF_ APPEND 
MF_ DELETE 

MF_ BYPOSITION 


MF_ BYCOMMAND 
MF_ GRAYED 

MF_ ENABLED 
MF_ DISABLED 
MF_ CHECKED 
MF_ UNCHECKED 


MF_ MENUBREAK 


MF_ MENUBARBREAK 


MF_ SEPARATOR 


MF_ BITMAP 
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Meaning 


Change or replace the specified item. 

Insert a new item just before the specified item. 
Append the new item to the end of the menu. 
Delete the item. 


wlDChangeltem gives the position of the menu 
item to be changed rather than an ID number. 


wiDChangeltem gives the menu item ID number 


(default). 


Disable and gray the item to show that it cannot 
be selected. 


Enable the item, allowing it to be selected 
(default). 


Disable the item without changing its appearance 
(it cannot be selected). 


Place a checkmark next to the item (popup menu 
item only). 


Do not place a checkmark next to the item 
(default). 


For static ae bar) menus, place the item on a 
new line. For popup menus, place the item in a 
new column, with no dividing line between the 
columns. 


Same as MF_ MENUBARBREAK, except that for 
popup menus, separate the new column from the 
old column with a vertical divider line. 


Draw a horizontal dividing line. Can only be used 
in popup menus. Cannot be enabled, checked, 
grayed, or highlighted. /pNewltem and 
wlDNewltem are ignored. 


Use a bitmap as the item. The low-order word of 
lpltem is a handle specifying the bitmap. 


Window Functions 


Table 2.3 (continued) 


Flag 
MF_ STRING 


MF_ POPUP 


Note 


Meaning 


Use a string as the item (default). ipNewltem is a 
long pointer to a null-terminated ASCII string. 


Associates a popup menu with a menu item. The 
wlDNewltem parameter is a handle to the menu. 
Can only be used with top-level menu items. 


When the user selects a menu item it is 
automatically highlighted. To control highlighting 
of menu items, use the HiliteMenultem function. 


DrawMenuBar ( hWnd ) 


Purpose 


Parameters 


This function redraws the menu bar. If a menu bar is 
changed after Windows has created the window and drawn 
the menu bar for the first time, this function should be 
called to draw the changed menu bar. 


hWnd is a handle to the window whose menu needs redraw- 
ing. 


Return Value None. 


CheckMenultem ( hMenu, wlDCheckItem, wCheck ) : bOldCheck 


Purpose 


Parameters 


This function places or removes checkmarks from menu 
items in the popup menu specified by hMenu. The w/D- 
Checkltem parameter specifies the item to be modified. 


hMenu is a handle to a menu. 


wlDCheckltem is an unsigned short integer value identifying 
the menu item to be checked. 


wCheck, an unsigned short integer value, consists of one or 
more of the following values, combined with the bitwise OR 
operator: 
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Value Meaning 


MF_ CHECKED Checkmark is added. 
MF_ UNCHECKED Checkmark is removed. 
MF_ BYPOSITION The wlDCheckltem parameter 


gives the position of the menu 
item (the first item is at posi- 
tion zero.) 


MF_ BYCOMMAND The wlDCheckltem parameter 
ives the menu item ID 
MF_ BYCOMMAND is the 
default). 


Return Value bOldCheck, a Boolean value, gives the previous state of the 


Notes 


item. It is either MF_ CHECKED or MF_ UNCHECKED. 


The wiDCheckltem parameter may identify a submenu item 
as well as a menu item. No special steps are required to 
check a submenu item. 


Top-level menu items cannot be checked. 


EnableMenultem ( hMenu, wIDEnableltem, wEnable ) : bEnabled 


Purpose 


Parameters 


This function enables, disables, or grays a menu item. 
hMenu is a handle to a menu. 


wiDEnableltem is an unsigned short integer value identifying 
the menu item to be checked. The w/DEnableltem parameter 
can specify submenu items as well as menu items. No spe- 
cial steps are required to enable a submenu item. 


wEnable is an unsigned short integer value specifying the 
action to take. It can be one or more of the following 
values, combined with the bitwise OR operator: 


Value Meaning 

MF_ GRAYED Menu item Is grayed. 
MF_ ENABLED Menu item is enabled. 
MF_ DISABLED Menu item is disabled. 


Window Functions 


MF_ BYPOSITION The w/DEnableltem parameter 
gives the position of the menu 
item (the first item is at posi- 
tion zero.) 


MF_ BYCOMMAND The w/DEnableltem parameter 
ives the menu item ID 
(MF BYCOMMAND is the 
default). 


Return Value bEnabled is a Boolean value specifying the previous state of 


Notes 


the menu item. 


To disable or enable input to a menu bar, see the 


WM_SYSCOMMAND message in Chapter 8. 


HiliteMenultem ( hWnd, hMenu, wlDHiliteltem, wHilite ) : bHilited 


Purpose 


Parameters 


This function highlights or removes the highlighting from a 
top-level (menu bar) menu item. 


hWnd is a window handle. 
hMenu is a handle to a top-level menu. 


wlDHiltteltem is either the control ID of the menu item or 
the offset of the menu item in the menu, depending on the 
value of the wHiltte parameter. 


wHtltte is an unsigned short integer value containing one or 
more of the following values. The values can be combined 
using the bitwise OR operator. 


Value Meaning 


MF_ BYCOMMAND Interpret the wlDHultteltem 
arameter as the menu item ID 
the default interpretation). 


MF_ BYPOSITION Interpret the w/DHiltteltem 


parameter as an offset. 

MF_ HILITE Highlight the item. If this flag 
is not given highlighting is 
removed from the item. 


MF_ UNHILITE Remove highlighting from the 


item. 
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Return Value O6Huiltted, a Boolean value, is nonzero if the item is 


Notes 


highlighted. Otherwise, it is zero. 


The MF_ HILITE and MF_ UNHILITE flags can be used only 
with the HiliteMenultem function; they cannot be used 
with ChangeMenu. 


GetSubMenu ( hMenu, nPos ) : hPopupMenu 


Purpose 


Parameters 


This function retrieves the menu handle of a popup menu. 
hMenu is a handle to a menu. 


nPos is a short integer value specifying the position in the 
given menu of the popup menu. Position values start at 0 
for the first menu item. The popup menu’s ID cannot be 
used in this function. 


Return Value hPopupMenu is a handle to the given popup menu. It is 


NULL if no popup menu exists at the given position. 


GetSystemMenu ( hWnd, bRevert ) : hSysMenu 


Purpose 


Parameters 


Return Value 


Notes 


This function allows access to the system menu for copying 
and modification. 


hWnd is a handle to the window that will own a copy of the 
system menu. 


bRevert is a Boolean value that specifies the action to be 
taken. If bRevert is zero, GetSystemMenu returns a han- 
dle to a copy of the system menu. This copy is initially 
identical to the system menu, but can be modified. 


If bRevert is nonzero, GetSystemMenu destroys the possi- 
bly modified copy of the system menu (if there is one 
belonging to the specified window and returns a handle to 
the original, unmodified version of the system menu. 


hSysMenu is a handle to the system menu if bRevert is 
nonzero. If bRevertis zero, hSysMenu is a handle to a copy 
of the system menu. 


Any window that does not use GetSystemMenu to make 
its own copy of the system menu gets the standard system 
menu. 


The handle returned by GetSystemMenu can be used with 
the ChangeMenu function to change the system menu. 
The system menu initially contains five items, with the fol- 
lowing ID values: 


Window Functions 


SC_ SIZE 
SC_ MOVE 
SC_ ICON 
SC_ ZOOM 
»C_ CLOSE 


The following system menu ID values are predefined and 
available for use on the application’s system menu: 


Value Meaning 


SC_ NEXTWINDOW Make the next window active. 
SC_ PREVWINDOW Make the previous window 


active. 

SC_ VSCROLL Assume a movement on the 
vertical scroll bar. 

SC_ HSCROLL Assume a movement on the 


horizontal scroll bar. 


SC_ MOUSEMENU Assume a mouse-activated 


menu. 


SC_ KEYMENU Assume a keyboard-activated 


menu. 


Menu items on the system menu send WM_SYSCOMMAND 
messages. All predefined system menu items have ID 
numbers greater than F000 (hexadecimal). If an application 
adds commands to the system menu, it should use ID 
numbers less than F000. 


Windows automatically grays items on the standard system 
menu, depending on the situation. The application can carry 
out its own checking or graying by responding to the 
WM_INITMENU message, which is sent before any menu is 
pulled down. . 


GetMenuString ( hMenu, wlDItem, lpString, nMazCount, wFlag ) 
: nCopted 


Purpose This function copies the label of the specified menu item 
into lpString. 
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Parameters hMenu is a handle to the menu. 


wlDItem is either the ID of the menu item (from the resource 
file) or the offset of the menu item in the menu, depending 
on the value of wF lag. 


lpString is a long pointer to the buffer to receive the label. 


nMazxCount is a short integer value specifying the maximum 
length of the label to be copied. If the label is longer than 
nMazCount, the extra characters are truncated. 


wFlag, an unsigned short integer value, is either 

MF_ BYPOSITION or MF_ BYCOMMAND. 

MF_ BYPOSITION causes the w/DItem parameter to be 
interpreted as an offset, while MF_ BYCOMMAND causes 
wlDItem to be interpreted as the control ID of the menu 
item. 


Return Value nCopzted is a short integer value specifying the number of 
bytes copied to the buffer. 


2.13 Window Painting Functions 


This section describes the functions used to prepare the client area of a 
window for graphics operations. 


GetDC ( AWnd): hDC 


Purpose This function retrieves the display context for the client 
area of the specified window. The display context can be 
used in subsequent GDI functions to draw in the client area. 


If the window class of the window specified by hWnd does 
not have CS_OWNDC style, GetDC must be called before 
any drawing is done in the window, and ReleaseDC must 
be called when drawing is finished. GetDC returns a han- 
dle to the default display context, which has the following 
characteristics: 
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Attribute 


Brush 

Pen 

Bitmap 

Font 

Current Pen Position 
Brush Origin 
Relabs Flag 

Text Color 
Background Color 
Background Mode 
Drawing Mode 
Stretching Mode 
Mapping Mode 


Intercharacter Spacing 


Polygon Filling Mode 
Color Table 


Clipping Region 
Window Origin 
Window Extents 
Viewport Origin 
Viewport Extents 


Window Functions 


Default Selection 


WHITE_ BRUSH 
BLACK_ PEN 

No default 
SYSTEM_ FONT 
(0,0) 

(0,0) 

ABSOLUTE 
Black 

White 

OPAQUE 

R2_ COPYPEN 
BLACKONWHITE 
MM_ TEXT 

0 

ALTERNATE 


Entries are set to represent an 
even distribution of the full 
range of available colors. The 
exact default values depend on 
the device. For example, raster 
devices have black as the first 
entry, white as the last; 
printers have white as the first 
entry, black as the last. 


The whole display surface 
(0, 0) 
(1, 1) 
(0, 0) 


(1, 1) 


The attributes of the display context can be changed using 
the selection functions and display context attribute func- 
tions described in Chapter 3. 
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Parameters 


Normally, all state information (currently selected brush, 
map mode, clipping region, etc.) that was selected into the 
display context after a GetDC call is lost after a 
ReleaseDC call. If a window belongs to a class that has 
CS_ OWNDC style, however, the state information of a 
display context is preserved, meaning that attributes such 
as clipping region, currently selected brush, etc., remain 
selected until the application specifically makes a change. 
The handle to the display context returned by GetDC 
remains valid, even if ReleaseDC is called. 


If the window specified by hWnd belongs to a class with 
CS_CLASSDC style, all windows in the same class use the 
same display context. Each call to GetDC with a different 
window from the same class returns the same display con- 
text handle. State information for the display context is 
retained, except that the clipping region, window origin, and 
window extents are reset to the default values each time 
GetDC is called for a new window. The sequence of getting 
and releasing the display context must be followed for each 
window in the class; it is an error to call GetDC for two 
different windows in the same class without first calling 
ReleaseDC to release the display context for the first win- 
dow. 


hWnd is a handle to a window. If hWndis NULL, a saved 


display context is returned. 


Return Value If the function is successful, ADC is a handle to the display 


Notes 


context for the given window’s client area. Otherwise, it is 


NULL. 


Only five display contexts are available in the Windows sys- 
tems at a given time (not counting display contexts allo- 
cated by giving a window class CS_CLASSDC or 
CS_OWNDC style.) ReleaseDC should be called promptly 
after finishing with a display context to free the display con- 
text for use by other windows and applications. 


Get WindowDC ( hWnd): hDC 


Purpose 
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This function retrieves the display context for the entire 
window, including caption bar, menus, and scroll bars. The 
origin of the display context is the upper left corner of the 
window, which corresponds to the upper left corner of the 
caption bar. 


Parameters 


Window Functions 


hWnd is a handle to a window. 


Return Value ADC is a handle to the display context for the given window 


Notes 


if the function is successful. Otherwise, it is NULL. 


Using the display context returned by Get WindowD(C, it is 
possible to draw anywhere in the window, even in the cap- 
tion bar, menus, and scroll bars. Use GetSystemMetrics 
to get the dimensions of the caption bar, menu areas, and 
scroll bars, or GetDC to get the display context of the 
window’s client area. 


The display context returned by GetWindowDC should be 
released using ReleaseDC when drawing is finished. Unlike 
GetDC, state information (such as the currently selected 
brush or map — is not preserved when ReleaseDC is 
called, even if the class to which the specified window 


belongs has CS_ OWNDC or CS_ CLASSDC style. 


ReleaseDC ( hWnd, hDC'): nReleased 


Purpose 


Parameters 


Return Value 


Notes 


This function is used to release a display context when an 
application is finished drawing in it. 


hWnd is a handle to a window. 
hDC is a handle to the display context. 


nReleased, a short integer value, is 1 if the display context is 
released. Otherwise, it is 0. 


For each call to GetDC or GetWindowDC, there should 
be a matching call to ReleaseDC. 


Only five display contexts are available in the Windows sys- 
tems at a given time (not counting display contexts allo- 
cated by giving a window class CS_CLASSDC or 
CS_OWNDC style). ReleaseDC should be called promptly 
after finishing with a display context to free the display con- 
text for use by other windows and applications. 


BeginPaint ( hWnd, IpPaint ): hDC 


Purpose 


This function prepares the given window for painting and 
fills the paint structure pointed to by /[pPatnt with informa- 
tion about the painting, such as the area of the screen that 


needs redrawing. If necessary, a WM_ERASEBKGND mes- 


sage is sent to the window. 
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Parameters 


Return Value 


Notes 


hWnd is a handle to the window to be repainted. 


lpPatnt is a long pointer to a data structure having 


PAINTSTRUCT type. 


hDC is the display context for the specified window. The 
clipping region of the display context includes only the part 
of the client area that needs redrawing. 


If the caret is in the area to be painted, BeginPaint 
automatically hides the caret to prevent overwriting. 


EndPaint ( hWnd, IpPaint ) 


Purpose 


Parameters 


Return Value 
Notes 


This function marks the end of repainting by the window 
and is required after each BeginPaint call. 


hWnd is a handle to the window that has been repainted. 


lpPatnt is a long pointer to a data structure having 


PAINTSTRUCT type. 
None. 


If the caret was hidden by the BeginPaint function, 
EndPaint restores the caret to the screen. 


Update Window ( hWnd ) 


Purpose 


Parameters 
Return Value 
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This function is used to ensure that a window’s appearance 
is up-to-date. It notifies the application when parts of a 
window need redrawing after the window is changed (by 
resizing, scrolling, etc.) UpdateWindow also checks child 
windows of the specified window to determine if they need 
updating. 


Update Window sends WM_ PAINT messages directly to 
the window function of the specified window, bypassing the 
application queue, with the result that the window has been 
repainted by the time Update Window returns. 


If no repainting is necessary, no message is sent. 
hWnd is a handle to the window to be updated. 


None. 


Window Functions 


GetUpdateRect ( hWnd, IpRect, bErase ): bUpdate 


Purpose 


Parameters 


Return Value 


Note 


This function returns the rectangle that bounds the region 
of the window that needs updating. 


hWnd is a handle to the window to be checked. 


lnRect is a long pointer to a RECT data structure. 

Get UpdateRect fills the structure with the coordinates of 
the rectangle bounding the area that needs updating. The 
coordinates are 0,0,0,0 (null) if no updating is necessary. 


bErase is a Boolean value specifying whether GetUp- 
dateRect should send a WM_ERASEBKGND message to 
erase the background of the update area. If the update 
region is not null and bE#rase is nonzero, the message is sent. 


bUpdate, a Boolean value, is nonzero if any area of the win- 
dow needs updating. If the window is up-to-date, bUpdate is 
zero. 


The rectangle coordinates provided by GetUpdateRect are 
the same as the coordinates given in the PAINTSTRUCT 


data structure after BeginPaint is called. 


InvalidateRect ( hWnd, lpRect, bErase ) 


Purpose 


Parameters 


Return Value 
Notes 


This function marks for repainting a rectangular area within 
the specified window. The [pRect parameter defines the 
rectangle, in client coordinates, enclosing the area to be 
repainted. If bHrase is nonzero, the contents of the rectan- 
gle are erased when marked; if zero, the contents remain 
unchanged. 


hWnd is the handle of the window to be repainted. 


lnRect is a long pointer to a data structure having RECT 
type that specifies the rectangle (in client coordinates) to be 
repainted. If lpRect is NULL, the entire window is invali- 
dated. | 


bErase is a Boolean value specifying whether or not the 
given rectangle needs to be erased. 


None. 


InvalidateRect does not cause the given rectangle to be 
repainted immediately. It sends a WM_ PAINT message, 
and the application eventually repaints the area in response 
to the message. If InvalidateRect is called more than once 
for the same window before GetMessage, PeekMessage, 
or Update Window is called, the rectangles given in each 
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call are combined into a single update region. The 
WM~_ PAINT message that an application eventually 
receives (by calling GetMessage, PeekMessage, or 
Update Window) gives the entire update region. 


InvalidateRgn ( hWnd, hRgn, bErase ) 


Purpose 


Parameters 


Return Value 
Notes 


This function marks for repainting a region within the 
display screen of the specified window. The hRgn parameter 
defines the region to be repainted. If bErase is nonzero, the 
contents of the region are erased when marked; if zero, the 
contents remain unchanged. 


hWnd is the handle of the window to be repainted. 


hRgn is a handle to a region, assumed to be in client coordi- 
nates. 


bHrase is a Boolean value specifying whether or not the 
screen is to be erased. 


None. 


InvalidateRgn has the same effect as InvalidateRect, 
except that a handle to a region is passed instead of a 
pointer to a rectangle. 


InvalidateRgn does not cause the given region to be 
repainted immediately. It sends a WM_ PAINT message, 
and the application eventually repaints the area in response 
to the message. If InvalidateRgn is called more than once 
for the same window before GetMessage, PeekMessage, 
or Update Window is called, the regions given in each call 
are combined into a single update region. The WM_ PAINT 
message that an application eventually receives (by calling 
Get Message, PeekMessage, or Update Window) gives 
the entire update region. 


ValidateRect ( hWnd, IpRect ) 


Purpose 
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This function releases from repainting a previously marked 
rectangular area of the display screen in the window 
specified by hWnd. The lpRect parameter specifies the 
dimensions, in client coordinates, of the rectangular area to 
be released. If lpRect is NULL, the entire window is vali- 
dated. 


Parameters 


Return Value 
Notes 


ValidateRgn 


Purpose 


Parameters 


Return Value 
Notes 


Window Functions 


hWnd is a handle to the window containing the area. 


lnRect is a long pointer to a data structure having RECT 
type. The rectangle coordinates are assumed to be client 
coordinates. 


None. 


ValidateRect or ValidateRgn should be called every time 
part of a window is updated. This prevents the screen from 
being redrawn twice. 


( hWnd, hRgn) 


This function releases from repainting a previously marked 
region in the display screen of the window specified by 
hWnd. The hRgn parameter specifies the region to be 
released. If hRgnis NULL, the entire window is released. 


hWnd is a handle to the window containing the area. 


hgn is a handle to a region, assumed to be in client coordi- 
nates. 


None. 


ValidateRgn is the same as ValidateRect, except that a 
handle to a region is passed instead of a pointer to a rectan- 
gle. 


ValidateRect or ValidateRgn should be called every time 
part of a window is updated. This prevents the screen from 
being redrawn twice. 


2.14 Scrolling Functions 


This section describes the functions used to scroll the contents of a 
window’s client area and control the window’s scroll bars. 


ScrollWindow ( hWnd, XAmount, YAmount, lpRect, lpClipRect ) 


Purpose 


This function scrolls a window by moving the contents of 
the window’s client area XAmount units along the screen’s 
x-axis and YAmount units along the y-axis. The contents of 
the window scroll left if XAmount is positive and right if it 
is negative. The contents of the window scroll down if 
YAmount is positive and up if it 1s negative. 
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Parameters 


Return Value 
Notes 
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hWnd is a handle to a window. 


XAmount is the amount (in device units) to scroll in the X 
direction. 


YAmount is the amount (in device units) to scroll in the Y 
direction. 


lnRect is a long pointer to a data structure having RECT 
type. The rectangle specifies what portion of the window’s 
client area should be scrolled. If lpRect is NULL, the entire 
client area is scrolled, and the caret position is adjusted 
accordingly. 


loClipRect is a long pointer to a data structure having 
RECT type. Only bits inside this rectangle are affected by 
the scroll. If lpClipRect is NULL, the entire window is 
affected. 


None. 


If the caret is in the window being scrolled, ScrollWindow 
automatically hides the caret to prevent overwriting, then 
restores the caret after the scroll is finished. 


The area “uncovered” by ScrollWindow is not repainted 
by ScrollWindow, but is combined into the window’s 
update region. The application will eventually receive a 
WM_ PAINT message notifying it that the region needs 
repainting. To repaint the uncovered area at the same time 
the scrolling is done, call UpdateWindow immediately 
after calling ScrollWindow. 


If lpRect is NULL, then the positions of any child windows 
in the window are offset by XAmount and YAmount, and 
any invalid (unpainted) areas in the window are offset as 
well. ScrollWindow is somewhat faster when [pRect is 


NULL. 


If lpRect is not NULL, then the positions of child windows 
are NOT changed, nor are invalid areas in the window 
offset. To prevent updating problems when [pRect is not 
NULL, calling Update Window to repaint the window 
before calling ScrollWindow is recommended. 


Window Functions 


SetScrollPos ( hWnd, nBar, nPos, bRedraw ): nOldPos 


Purpose 


Parameters 


This function sets the current position of a scroll bar eleva- 
tor to nPos, and if specified, redraws the scroll bar to reflect 
the new position. 


hWnd is a handle to the window whose scroll bar is to be set. 


nBar is one of the following short integer values, specifying 
which scroll bar to set: 


Value Meaning 

SB_ VERT Set the vertical scroll bar position. 

SB_ HORZ Set the horizontal scroll bar posi- 
tion. 

SB_ CTL Set a scroll bar control; in this case, 


the hWnd parameter specifies the 
child window handle of the scroll 
bar control. 


nPos is a short integer value specifying the new position. It 
must be within the range specified by the SetScrollRange 
function. 


bRedraw is a Boolean value specifying whether or not the 
scroll bar should be redrawn to reflect the change. If 
bedraw is nonzero, the scroll bar is redrawn. If zero, it is 
not redrawn. Setting the bRedraw parameter to zero is use- 
ful whenever the scroll bar will be redrawn by a subsequent 
call to another function. 


Return Value nOldPos is a short integer value specifying the previous posi- 


tion of the scroll bar elevator. 


GetScrollPos ( hWnd, nBar ): nPos 


Purpose 


Parameters 


This function retrieves the current position of a scroll bar 
elevator. 


hWnd is a handle to the window whose scroll bar is to be 
examined. 


nBar is a short integer value specifying which scroll bar to 
examine. If nBar is SB_ VERT, the function examines the 
vertical scroll bar; if nBar is SB_- HORZ, it examines the hor- 
izontal scroll bar. The SB_ CTL value indicates that the 
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operation is to take place on a scroll bar control rather than 
on a standard scroll bar; in this case, hWnd specifies the 
child window handle of a scroll bar control. 


Return Value nPosis a short integer value specifying the current position 


of the scroll bar elevator. 


SetScrollRange ( hWnd, nBar, nMinPos, nMazPos, bRedraw ) 


Purpose 


Parameters 


Return Value 
Notes 


80 


This function sets minimum and maximum position values 
for the scroll bar of the specified window. It can also be 
used to add or remove a window’s scroll bar. 


The default scroll range is 0 to 100, but this range can be 
reset to any useful values. For example, a spreadsheet pro- 
gram with 255 rows can set the vertical scroll range to 1 to 
255. 


hWnd is a handle to the window whose bar is to be set. 


nBar is one of the following short integer values, specifying 
which scroll bar to set: 


Value Meaning 

SB_ VERT Set the vertical scroll bar position. 

SB_ HORZ Set the horizontal scroll bar posi- 
tion. 

SB_ CTL Set a scroll bar control; in this case, 


the hWnd parameter specifies the 
child window handle of a scroll bar 
control. 


nMinPos and nMazPos are short integer values specifying 
the minimum and maximum scrolling positions, respectively. 
If nMinPos is equal to nMazPos, the scroll bar is removed. 


bRedraw is a Boolean value specifying whether or not the 
scroll bar should be redrawn to reflect the change. If 
bRedraw is nonzero, the scroll bar is redrawn. If zero, it is 
not redrawn. 


None. 


When a scroll bar is being hidden or removed, the window is 
always updated to reflect the change, regardless of the value 
of the 6Redraw parameter. 


Window Functions 


If a scroll bar is removed, you can restore it by calling 
SetScrollRange with unequal minimum and maximum 
values. 


If SetScrollRange immediately follows SetScrollPos, 
bRedraw in SetScrollPos should be set to zero to prevent 
the scroll bar from being drawn twice. 


GetScrollRange ( hWnd, nBar, lpMinPos, lpMazPos ) 


Purpose 


Parameters 


This function retrieves the current minimum and maximum 
scroll bar positions for the given scroll bar and saves the 
values in the locations specified by lpMinPos and lpMazPos. 


hWnd is a handle to the window to be examined. 


nBar is one of the following short integer values, specifying 
which scroll bar to set: 


Value Meaning 

SB_ VERT Set the vertical scroll bar position. 

SB_ HORZ Set the horizontal scroll bar posi- 
tion. 

SB_ CTL Set a scroll bar control; in this case, 
the hWnd parameter specifies the 
control. 


lpMinPos is a long pointer to the short integer variable to 
receive the minimum position. 


lpMazxPos is a long pointer to the short integer variable to 
receive the maximum position. 


Return Value None. 


2.15 Property List Functions 


This section describes the functions used to access the property list of a 


window. 
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SetProp ( hWnd, IpString, hData ) : bSet 


Purpose 


Parameters 


Return Value 


Note 


This function copies a character string and a data handle to 
the property list of the window specified by hWnd. The 
string, pointed to by lpString, serves as a label for the data 
handle hData. The data handle can be retrieved from the 
property list at any time by using the GetProp function 
and specifying the string. 


hWnd is a handle to a window. 


lnString is either a long pointer to a character string or an 
atom identifying a string. If the low-order word of [pString is 
in the range 0 to BFFF (hexadecimal) and the high-order 
word is zero, it is treated as an atom. 


hData is a handle to an arbitrary data structure. 


bSet, a Boolean value, is nonzero if the function is successful. 
Otherwise, it is zero. 


The application must free any data handles in a window’s 
property list before it destroys the window. 


GetProp ( AWnd, IpString ) : hData 


Purpose 


Parameters 


This function searches the window’s property list for a data 
handle associated with the string pointed to by IpString. 


hWnd is a handle to a window. 


lpString is either a long pointer to a character string or an 
atom identifying a string. If the low-order word of lpString 
is in the range 0 to BFFIF (hexadecimal) and the high-order 
word is zero, it is treated as an atom. 


Return Value If the function is successful, hData is a handle to an arbi- 


trary data structure. Otherwise, it is NULL. 


RemoveProp ( hWnd, lpString ) : hData 


Purpose 


Parameters 
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This function removes the specified string from the window 
property list and retrieves the data handle named by that 
string so that the data associated with the handle can be 
freed. 


hWnd is a handle to a window. 


lp String is a long pointer to a null-terminated ASCII string 
or an atom identifying a string. If the value is in the range 
0 to BFFF (hexadecimal), it is treated as an atom. 


Window Functions 


Return Value ADatais a handle to an a data structure named by the string 


if the function is successful. Otherwise, it is NULL. 


EnumProps ( AWnd, lpEnumFunc ): nResult 


Purpose 


Parameters 


Return Value 


Notes 


This function enumerates all the properties of the specified 
window. The properties are passed, one by one, to the 
application-supplied function specified by lpHnumFunc. The 
function continues until the last property is enumerated or 
the function returns zero. 


hWnd is a handle to a window. 


lpEnumF unc is a long pointer to a application-supplied func- 
tion. 


nResult, a short integer value, is equal to the last value 
returned by the application-supplied function. 


The application-supplied function must have the form 
functionname (hWnd, lpString, hData) : bContinue 


where hWnd is a handle to a window and /AData is an arbi- 
trary handle. 


The function can carry out any desired task. It must return 
a nonzero value to continue enumeration. It can return zero 
to stop the enumeration. 


The [pString parameter is a far pointer to a buffer on the 
stack. If the stack segment is the same as the data segment 
(a STACKSIZE statement is included in the application’s 
.DEF file), and the data segment moves as a result of local 
memory allocation, this far pointer will be invalidated. 
Therefore, if SS=—DS, the application-supplied function is 
declared as follows: 


functionname (hWnd, nDummy, pString, hData) : bContinue 
where nDummy is an unused short integer variable and 


pString is a short pointer to a string. The other parameters 
and the return value are the same as described above. 
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2.16 Window Attribute Functions 


This section describes the functions used to access and modify the attri- 
butes of a window. 


SetWindowText ( hWnd, lpString ) 


Purpose 


Parameters 


This function sets the given window’s caption title (if it has 
one) to the string pointed to by lpString. If hWnd is a han- 
dle to a control, Set WindowText sets the text within the 
control instead of the caption. 


hWnd is a handle to the window or control whose text is to 
be changed. 


lpString is a long pointer to a null-terminated string. 


Return Value None. 


Get WindowText ( hWnd, lpString, nMaxCount ) : nCopied 


Purpose 


Parameters 


This function copies the given window’s caption title (if it 
has one) into the buffer pointed to by lpString. If hWnd is a 
handle to a control, Get Window Text copies the text 
within the control instead of the caption. 


hWnd is a handle to the window or control whose caption or 
text is to be copied. 


lpString is a long pointer to the buffer to receive the copied 
string. 


nMazCount is a short integer value specifying the maximum 
number of characters to be copied to the buffer. 


Return Value nCopied is a short integer value specifying the length of the 


copied string. It is 0 if the window has no caption. 


Get Window TextLength ( hWnd ): nLength 


Purpose 


Parameters 
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This function returns the length of the given window’s cap- 
tion title. If hWnd is a handle to a control, Get Win- 

dow TextLength returns the length of the text within the 
control instead of the caption. 


hWnd is a handle to the desired window or control. 


Window Functions 


Return Value nLength is a short integer value specifying the text length. 
It is 0 if no such text exists. 


Find Window ( /[pClassName, lp WindowName ) : hWnd 


Purpose This function returns the handle of the window whose class 
is given by [pClassName and whose window name (caption) 
is given by lp WindowName. 


Parameters [lpClassName is a long pointer to a null-terminated string 
specifying the window’s class name. If [pClassName is 
NULL, all class names match. 


lp WindowName is a long pointer to a null-terminated string 
specifying the the window name (that is, the window’s text 
caption). If lpWindowName is NULL, all window names 
match. 


Return Value hWnd is the window handle of the window that has the 
specified class name and window name. It is NULL if no 
such window is found. 


GetParent ( hWnd ) : hWndParent 
Purpose This function retrieves the window handle of the specified 
window’s parent (if any). 


Parameter hWnd is a handle to the window whose parent window han- 
dle is to be retrieved. 


Return Value hWndParent is a handle to the parent window. It is NULL if 
the window has no parent. 


GetClientRect ( hWnd, lpRect ) 


Purpose This function copies the client coordinates of a window’s 
client area into the data structure pointed to by lpRect. 
The client coordinates specify the upper left and lower right 
corners of the client area. Since client coordinates are rela- 
tive to the upper left corner of a window’s client area, the 
coordinates of the upper left corner are 0,0. 


Parameters hWnd is a handle to a window. 


lpRect is a long pointer to a data structure having RECT 
type. 
Return Value None. 
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Get WindowRect ( hWnd, Iplect ) 


Purpose This function copies the dimensions of the bounding rectan- 
gle of the specified window into the structure pointed to by 
lnRect. The dimensions are given in screen coordinates, 
relative to the top left corner of the display screen, and 
include the caption, border, and scroll bars, if present. 


Parameters hWnd isa handle to a window. 
infect is a long pointer to a data structure of RECT type. 


Return Value None. 


GetSysModalWindow ( ): hWnd 


Purpose This function returns the handle of a system modal window, 
if one is present. 


Parameters None. 


Return Value hWnd is a handle to the system modal window, if one is 
present. If no such window is present, hWnd is NULL. 


SetSysModal Window ( hWnd ): hPrevWnd 


Purpose This function makes the specified window a system modal 
window. 
Parameter hWnd is a handle to the window to be made system modal. 


Return Value hPrevWnd is a handle to the window that was previously the 
system modal window. 


Notes If another window is made the active window (for example, 
the system modal window creates a dialog box that becomes 
the active window), the active window becomes the system 
modal window. When the original window becomes active 
again, it is system modal. To end the system modal state, 
destroy the window that is system modal. 
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2.17 Error Functions 


This section describes the functions used to display errors and prompt for a 


user response. 


MessageBox ( hAWndParent, lp Text, lpCaption, wT ype ) : nMenultem 


Purpose 


Parameters 


This function creates and displays a window that contains a 
application-supplied message and caption, plus any combi- 
nation of the predefined icons and push buttons described 
below. 


hWndParent is a handle to the window that owns the mes- 
sage box. The input focus is set to this window when Mes- 
sageBox returns. 


ln Text is a long pointer to the message to be displayed. The 
string must be a null-terminated ASCII string. 


lpCaptton is a long pointer to the character string to be used 
for the dialog box caption. The string must be null- 
terminated. If ipCaption is NULL, the default caption 
“Error!” is used. 


wl'ype is an unsigned short integer value specifying the con- 
tents of the dialog box. It can be any combination of the 
following values, joined with the bitwise OR operator: 


Value Meaning 

MB_ OK Message box contains an Ok 
push button. 

MB_ OKCANCEL Message box contains Ok and 


Cancel push buttons. 


MB_RETRYCANCEL Message box contains Retry 
and Cancel push buttons. 


MB_ ABORTRETRYIGNORE 
Message box contains three 
push buttons: Abort, Retry, 
and Ignore. 


MB_ YESNO Message box contains two push 
buttons: Yes and No. 
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MB_ YESNOCANCEL 


MB_ ICONHAND 


MB_ICONQUESTION 


Message box contains three 
push buttons: Yes, No, and 
Cancel. 


A hand icon appears in the 
message box. 


A question mark icon appears 
in the message box. 


MB_ ICONEXCLAMATION 


MB_ ICONASTERISK 


MB_ DEFBUTTONI 


MB_ DEFBUTTON2 
MB_ DEFBUTTONS 
MB_ APPLMODAL 


MB_SYSTEMMODAL 


An exclamation point icon 
appears in the message box. 


An asterisk icon appears in the 
message box. 


First button is the default (the 
first. button is always the 
default unless 

MB_ DEFBUTTON2 or 

MB_ DEFBUTTONS is 
specified). 


Second button is the default. 
Third button is the default. 


The user must respond to the 
message box before continuing 
work in the window given by 
hWndParent. However, the 
user can move to the windows 
of other applications and work 
in those windows. 

(MB_ APPLMODAL is the 
default.) 


All applications are suspended 
until the user responds to the 
message box. System modal 
message boxes are used to 
notify the user of serious, 
potentially damaging, errors 
that require immediate atten- 
tion (for example, running out 
of memory). 


Window Functions 


Return Value nMenultem is one of the following menu item values 


Notes 


returned by the dialog box: 


IDOK 
IDCANCEL 
IDABORT 
IDRETRY 
IDIGNORE 
IDYES 
IDNO 


If a message box has a “Cancel” button, the IDCANCEL 
value will be returned if either Escape or Cancel is pressed. 
If the message box has no “Cancel” button, pressing Escape 
has no effect. 


When a system modal message box is created to indicate 
that the user is low on memory, the strings passed as the 

lo Text and lpCaption parameters should not be taken from a 
resource file, since an attempt to load a resource file may 
fail. The message box can safely use the hand icon 

(MB_ HANDICON), since this icon is always resident and 


does not require disk access. 


When the keyboard interface is used to enumerate windows, 
the message box and its “parent” are considered to be 
“next” to each other. 


If a message box is created while a dialog box is present, use 
the handle of the dialog box as the hWndParent parameter. 


MessageBeep ( wT ype ): bBeep 


Purpose 
Parameter 


Return Value 


This function generates a “beep” at the system speaker 
when a message box is displayed. 


wI'ype is an unsigned short integer value that is the same as 
the w/'ype parameter passed to the MessageBox function. 


bBeep, a Boolean value, is nonzero if the function is success- 
ful, zero otherwise. 
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Flash Window ( hWnd, b/nvert ) : bInverted 


Purpose 


Parameters 


Return Value 


Notes 


This function “flashes” the given window once. Flashing a 
window means changing the appearance of its caption bar or 
icon as if the window were changing from inactive to active 
status, or vice versa. (A gray caption bar or unframed icon 
changes to a black caption bar or framed icon; a black cap- 
tion bar or framed icon changes to a gray caption bar or 
unframed icon.) 


The window is flashed from one state to the other if the 
bInvert parameter is nonzero. If the b/nvert parameter is 
zero, the window is returned to its original state (either 
active or inactive). 


A window is typically flashed to indicate to the user that the 
window requires attention, but that it does not currently 
have the input focus. 


hWnd is a handle to a window that is either open or iconic. 


bInvert, a Boolean value, is nonzero when the window is to 
be flashed. b/nvert is zero if the window is to be returned to 
its original state (active or inactive). 


bInverted, a Boolean value, is nonzero if the window’s state is 
inverted. It is zero if an error occurs. 


Flash Window flashes the window only once; for successive 
flashing, the application should create a system timer. 


bInvert should be zero only when the window is getting the 
input focus and will no longer be flashing; it should be 
nonzero on successive calls while waiting to get the input 
focus. 


2.18 Cursor Functions 


This section describes the functions used to set and move the mouse cursor. 
The mouse cursor is the primary pointing device used by Windows to pro- 
vide input to an application. 
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SetCursor ( hCursor ) : hOldCursor 


Purpose 


Parameters 


Return Value 


Notes 


This function sets the cursor shape to the cursor specified by 
hCursor. The cursor is set only if the new shape is different 
from the existing shape. Otherwise, the function returns 
immediately. If hCursor is NULL, the cursor is removed 
from the screen. 


hCursor is a handle to a cursor resource. The resource must 
have been loaded previously using the LoadCursor func- 
tion. 


hOldCursor is a handle to the cursor resource defining the 
previous cursor shape. It is NULL if there is no previous 
shape. 


This function is quite fast if hCursor is the same as the 
current cursor. 


The cursor is not shown on the screen if the cursor display 
count is less than zero (i.e., HideCursor has been called 
more times than ShowCursor.) 


SetCursorPos ( X, Y ) 


Purpose 
Parameters 


Return Value 
Notes 


This function sets the position of the mouse cursor to the 
screen coordinates given by X and Y. 


X and Y are integer values that specify the new screen coor- 
dinates of the mouse cursor. 


None. 


To set the cursor to a position relative to a window, convert 
client coordinates to screen coordinates using the Client- 
ToScreen function. 


ClipCursor ( [pRect ) 


Purpose 


Parameter 


This function is used to restrict the mouse cursor to a given 
rectangle on the screen. 


lpRect is a long pointer to a data structure having RECT 
type. The cursor will be restricted to the rectangle defined 
by the screen coordinates given in the structure. If [pRect is 
NULL, the cursor can use the entire screen. 


Return Value None. 
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GetCursorPos ( [pPoint ) 


Purpose This function gets the current position, in screen coordi- 
nates, of the mouse cursor and stores it in the structure 
pointed to by /pPoint. The position returned is the true 
position when GetCursorPos was called; this function is 
NOT synchronized with the GetMessage and PeekMes- 


sage functions. 


Parameter lpPoint is a long pointer to a data structure having POINT 
type. 
Return Value None. 


ShowCursor ( Show ) : nCount 


Purpose This function displays or hides the cursor. If bShow is 
nonzero, ShowCursor adds one to the display count. If 
bShow is zero, the display count is decreased by one. 


The cursor is displayed only if the display count is greater 
than or equal to zero. Initially, the display count is zero if a 
mouse is installed, —1 otherwise. 


Parameter bShow is a Boolean value that causes the display count to be 
increased if nonzero, and decreased if zero. 


Return Value nCount is the new value of the display count. 


Notes When a cursor is to be displayed in a mouseless environ- 
ment, the application is responsible for defining its own user 
interface for moving the cursor. 


2.19 Caret Functions 


This section describes the functions used to create, display, move, and 
destroy the system caret. The system caret is a flashing bitmap that can be 
moved to any location on the display screen. The caret is typically used in 
text applications to mark a location. 
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CreateCaret ( hWnd, hBitmap, nWidth, nHeight ) 


Purpose 


Parameters 


Return Value 
Notes 


This function creates a caret for the given window. The 
caret has the shape and dimensions of the bitmap specified 
by hBitmap. If hBitmap is NULL, however, the caret is a 
solid flashing black block nWtdth pixels wide by nHetght pix- 
els high; if hBitmap is 1, the caret is gray instead of black. 


The caret is initially hidden. The ShowCaret function 
must be called to display the caret. 


hWnd is a handle to the window to receive the new caret. 


hBitmap is a handle to the bitmap defining the caret shape. 
If hBitmap is NULL, the caret is a solid black block; if ABtt- 


map is 1, the caret is gray. 


nWidth and nHerght are integer values specifying the width 
and height of the caret. These values are used only if hBit- 
map is NULL or 1; otherwise, they are ignored. 


None. 


If nWidth or nHetght is 0, then the system nominal border 
width or height is used. These values can be obtained by 
calling GetSystemMetrics with SM_ CXBORDER and 
SM_ CYBORDER as indexes. The width of a text caret is 
usually set to 0. This is preferable to giving 1 as the nWedth 
argument, since on a high resolution device a width of 1 may 
produce a very thin line. 


Only one caret is available at a time, so it is not possible to 
have two carets flashing. An applications should create a 
caret only when it has the keyboard focus or is the active 
window. Creating carets at other times may stop the caret 
from flashing in another application. Similarly, when an 
application becomes inactive or loses the focus, its caret 
should be destroyed. 


DestroyCaret ( } 


Purpose 


Parameters 


This function destroys the current caret and frees any 
memory that it occupied. 


None. 


Return Value None. 
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Note 


An application must only call Destroy Caret if it has 
created a caret. Otherwise, the call to Destroy Caret may 
destroy the caret that is flashing in another application. 


HideCaret ( hWnd ) 


Purpose 


Parameters 


This function removes the system caret from the display 
screen, if the caret was created in the specified window. The 
caret is not destroyed; it can be redisplayed using the 

Show Caret function. 


hWnd is a handle to the window whose caret is to be hidden. 
If hWnd is NULL, the caret is hidden regardless of which 


window created it. 


Return Value None. 


ShowCaret ( hWnd ) 


Purpose 


Parameters 


Return Value 


This function displays a caret created with the 
CreateCaret function, or redisplays a caret that has been 
removed from the display screen using the HideCaret func- 
tion. The caret is displayed only if it was created in the 
specified window. If HideCaret has been called several 
times without any intervening calls to ShowCaret, an 
equal number of ShowCaret calls must be made before the 
caret is redisplayed. 


hWnd is a handle to the window whose caret is to be 
redisplayed. If hWnd is NULL, the caret is redisplayed 


regardless of which window created it. 


None. 


SetCaretPos ( X, Y) 


Purpose 


Parameters 


Return Value 
Note 
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This function moves the caret to the position specified by X 
and Y. The movement applies to the caret whether it is 
visible or hidden. 


X and Y are integer values specifying the new position of the 
caret, in client coordinates of the window for which the 
caret was created. 


None. 


The application is responsible for ensuring that SetCaret- 
Pos is called only when the caret is in the application’s own 
window. If SetCaretPos is called when the caret is in 
another window, the caret position will be changed. 
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SetCaretBlinkTime ( nMSeconds ) 
Purpose This function establishes the caret flash rate. 


Parameters nMSeconds is an integer value that gives the delay, in mil- 
liseconds. 


Return Value None. 


GetCaretBlinkTime ( ): nMSeconds 
Purpose This function returns the current caret flash rate. 
Parameters None. 


Return Value nMSeconds gives the delay, in milliseconds. 


2.20 Coordinate Functions 


This section describes the functions used to convert client coordinates to 
screen coordinates, and vice versa. Client coordinates refer to points within 
the client area of a window and are always relative to the upper left corner 
of the client area. Screen coordinates refer to points on the screen and are 
relative to the upper left corner of the screen. 


Client ToScreen ( hWnd, lpPoint ) 


Purpose This function converts the client coordinates of the point 
specified by /pPoint into equivalent screen coordinates. 
Screen coordinates are relative to the upper left corner of 
the screen and do not refer to any specific window. 


Client ToScreen assumes that the point to be converted 
lies inside the client area of the specified window. The func- 
tion copies the new screen coordinates into the location 
pointed to by lpPotnt, overwriting the original client coordi- 
nates. : 


Parameters hWnd is a handle to a window. 


lpPotnt is a long pointer to a data structure having POINT 
type. 
Return Value None. 


95 


Microsoft Windows Reference Manual 


ScreenToClient ( hWnd, lpPoint ) 


Purpose 


Parameters 


Return Value 


This function converts the screen coordinates of the point 
specified by /[pPoint into equivalent client coordinates. The 
point is assumed to be in screen coordinates. The new client 
coordinates replace the existing values in [pPount. 


hWnd is a handle to the window whose client area is used in 
the mapping. 


lpPotnt is a long pointer to a data structure having POINT 
type. 
None. 


WindowFromPoint ( Point): hWnd 


Purpose 


Parameters 
Return Value 


This function identifies the window that contains the given 
point. The Point parameter must specify the screen coordi- 
nates of a point on the screen. 


Point is a data structure of POINT type. 


hWnd is the handle of the window in which the point lies. It 
is NULL if no window exists at the given point. 


ChildWindowFromPoint ( hWndParent, Point ) : hWndChild 


Purpose 


Parameters 


This function determines which, if any, of the child windows 
belonging to the given parent window contains the specified 
point. 


hWndParent is a handle to the parent window. 


Point is a data structure with POINT type containing the 
client coordinates of the point to be tested. 


Return Value hWndChild is a handle to the child window containing the 


point. It is NULL if the given point lies outside the parent 
window. If the point is within the parent window but is not 
contained within any child window, the handle of the parent 
window is returned. 
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2.21 Rectangle Functions 


This section describes the utility functions used to create and modify rect- 
angle data structures. Rectangle data structures are required as input by 
many GDI functions. 


SetRect ( IpRect, X1, Y1, X2, Y2) 


Purpose 


Parameters 


Return Value 
Notes 


This function fills the structure pointed to by lpRect with 
the coordinates given by X1, Y1, X2, and Y2. 


lpRect is a long pointer to a data structure having RECT 
type. 


X1and Y1 are short integer values specifying the coordi- 
nates of the upper left corner of the rectangle. 


X2and Y2 are short integer values specifying the coordi- 
nates of the lower right corner of the rectangle. 


None. 


The width of the rectangle must not exceed 32K units. 


SetRectEmpty ( lpRect ) 


Purpose 
Parameters 


Return Value 


This function sets the rectangle to an empty rectangle (all 
coordinates zero). 


lpRect is a long pointer to a data structure having RECT 
type. 
None. 


CopyRect ( l[pDestRect, lpSourceRect ) 


Purpose 


Parameters 


Return Value 


This function makes a copy of an existing rectangle. 


lpDestRect is a long pointer to a destination data structure 


having RECT type. | 


lpSourcefect is a long pointer to a source data structure 


having RECT type. 


None. 
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InflateRect ( IpRect, X, Y ) 


Purpose 


Parameters 


Return Value 
Notes 


This function expands the rectangle specified by lpRect, 
increasing the width by X units on the left and right ends of 
the rectangle, and increasing the height by Y units on the 
top and bottom. If X or Y is negative, the width or height 
of the rectangle is decreased. 


lnRect is a long pointer to a data structure having RECT 
type. 


X is a short integer value specifying the amount to increase 
the rectangle width. If X is negative, the width is decreased. 


Y is a short integer value specifying the amount to increase 
the rectangle height. If Y is negative, the height is 
decreased. 


None. 


The width of the rectangle must not exceed 32K units. 


IntersectRect ( [pDestRect, lpSrc1Rect, lpSrc2Rect ) : nIntersection 


Purpose 


Parameters 


Return Value 


This function finds the intersection of two rectangles and 
copies it to the buffer specified by [pDestRect. 


lpDestRect is a long pointer to the buffer to receive the inter- 
section. It must have RECT type. 


loSrciRect is a long pointer to a data structure having 


RECT type. 


loSrc2Rect is a long pointer to a data structure having 


RECT type. 


nintersectton, an integer value, is nonzero if the intersection 
of the two rectangles is not empty. n/ntersectton is zero if 
the intersection is empty. 


UnionRect ( [pDestRect, lpSrciRect, lpSrc2Rect ): nUnion 


Purpose 


Parameters 
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This function creates the union of two rectangles. The 
union is equal to the smallest rectangle containing both 
source rectangles. 


lpDestRect is a long pointer to a data structure having 
RECT type. 


lpSrciRect is a long pointer to a data structure having 


RECT type. 
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lnSrc2Rect is a long pointer to a data structure having 
RECT type. 


Return Value nUnion, an integer value, is 1 if the union is not empty. It is 
0 if the union is empty. 
OffsetRect ( IpRect, X, Y ) 


Purpose This function moves the specified rectangle by the specified 
offsets. OffsetRect moves the rectangle X units along the 
x-axis and Y units along the y-axis. 


Parameters IpRectis a long pointer to a data structure having RECT 
type. 


X is a short integer value specifying the amount to move left 
or right. 


Y is a short integer value specifying the amount to move up 
or down. 


Return Value None. 


IsRectEmpty ( [pRect ) : bEmpty 


Purpose This function determines whether or not the specified rect- 
angle is empty. A rectangle is empty if the width or height 
is zero. 


Parameters  IpRectis a long pointer to a data structure having RECT 
type. 


Return Value bEmpty, a Boolean value, is nonzero if the rectangle is 
empty. Otherwise, it is zero. 


PtInRect ( [pRect, Point ): bInRect 


Purpose This function indicates whether or not a specified point lies 
within a given rectangle. 


Parameters  Ipltectis a long pointer to the rectangle to be checked. It 
must point to a data structure having RECT type. 


Point is a data structure having POINT type. 


Return Value 6InRect, a Boolean value, is nonzero if the point lies within 
the given rectangle. Otherwise, it is zero. 
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2.22 System Information Functions 


This section describes functions used to retrieve and change system charac- 


teristics. 


GetSystemMetrics ( n/ndez): nValue 


Purpose This function retrieves information about system metrics. 


Parameters nindezxis one of the following integer values, specifying 
which measurement is to be retrieved: 


Index 


SM_ CXSCREEN 
SM_ CYSCREEN 
SM_ CXVSCROLL 


SM_ CYVSCROLL 


SM_ CXHSCROLL 


SM_ CYHSCROLL 


SM_ CYCAPTION 
SM_ CXBORDER 


SM_ CYBORDER 


SM_ CXDLGFRAME 


SM_ CYDLGFRAME 


SM_ CYVTHUMB 
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Value 


Width of screen 
Height of screen 


Width of arrow bitmap on 
vertical scroll bar 


Height of arrow bitmap on 
vertical scroll bar 


Width of arrow bitmap on 
horizontal scroll bar 


Height of arrow bitmap on 
horizontal scroll bar 


Height of caption 


Width of left/right window 
border 


Height of top/bottom win- 
dow border 


Width of frame when win- 
dow has WS_ DLGFRAME 
style 


Height of frame when win- 
dow has WS_ DLGFRAME 
style 


Height of thumb box on 
vertical scroll bar 


SM_ CXHTHUMB 


SM_ CXICON 
SM_ CYICON 
SM_ CXCURSOR 
SM_ CYCURSOR 
SM_ CYMENU 


SM_ CXFULLSCREEN 


SM_ CYFULLSCREEN 


SM_ CYKANJIWINDOW 
SM_ MOUSEPRESENT 


SM_ DEBUG 
SM_ CMETRICS 


SM_ FULLSCREEN 


SM_ CURSORLEVEL 
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Width of thumb box on hor- 


izontal scroll bar 
Width of icon 
Height of icon 
Width of cursor 
Height of cursor 


Height of single line menu 
bar 


Width of window client area 
for full screen window 


Height of window client area 
for full screen window 
(equivalent to the height of 
the screen minus the height 
of the window caption) 


Height of Kanji window 


Non-zero if mouse hardware 
installed 


Non-zero if windows debug- 
ging version 


Number of system metrics 


Handle to full-screen win- 
dow; zero if no such window 
is present 


Cursor display count (see 
the ShowCursor function). 


Return Value nValue is an integer measurement =neee meaning depends 


on the n/ndez parameter. 


GetSysColor ( nIndez ) : rgbColor 


Purpose This function retrieves information about system colors. 


Parameter nindez is one of the following integer values, specifying the 
item whose color is to be retrieved: 
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Index Item 


COLOR_ SCROLLBAR Scroll bar “gray” area 
COLOR BACKGROUND Desktop 

COLOR_ ACTIVECAPTION Active window caption 
COLOR_INACTIVECAPTION 


Inactive window caption 


COLOR_ MENU Menu background 
COLOR WINDOW Window background and 
thumb box 


COLOR_ WINDOWIFRAME Window border, caption 
text background 


COLOR_ MENUTEXT Text in menus 
COLOR_ WINDOWTEXT Text in windows 
COLOR_ CAPTIONTEXT Text in caption, size box, 


scroll bar arrow box 


Return Value rgbColor is an RGB color value specifying the color of the 
specified item. 

SetSysColors ( nChanges, lpSysColor, lpColor Values ) 

Purpose This function changes one or more system colors. 


Parameters nChanges is an integer specifying the number of colors to be 
changed. 


loSysColor is a long pointer to an array of integer indexes 
specifying the items to be changed. The array consists of 


one or more of the index values described above for GetSys- 
Color. 


lpColor Values is a long pointer to an array of unsigned long 
integers that represent RGB color values. 


Return Value None. 


Note SetSysColors does NOT write the color change to the 
WIN.INI file. 
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2.23 Window Hook Function 


The window hook function is a general-purpose function for installing one 
of several kinds of “hooks” into Windows. When a particular type of 
application-supplied hook function is installed, Windows calls the hook 
function before carrying the normal Windows processing for that type of 
input or action. This allows the application to intercept and alter the nor- 
mal sequence of Windows processing. 


Set WindowsHook ( nFilterType, lpFilterFunc ) : lpPrevFilterFunc 


This function is used to install system and/or application 
hook functions. The purpose of each hook is explained 


Purpose 


Parameters 


below. 


nlilter Type is one of the following short integer values, indi- 
cating which hook is being installed: 


Value 
WH_ MSGFILTER 


WH_ KEYBOARD 


Meaning 


Install a message filter. The 
filter function pointed to by 
lpFilterFunc will be called 
whenever a message occurs, 
before Windows performs its 
default processing of the mes- 
sage. 


Install a keyboard filter. The 
filter function pointed to by 
lpFulterF'unc will be called 
whenever a WM_KEYUP or 
WM_KEYDOWN message 
occurs; the message is passed 
to the filter function before 
being sent to the window with 
the input focus. 


loFilterF'unc is a long pointer to the filter function to be 
installed. The function is passed a pointer to a MSG struc- 
ture and a code that indicates the Windows message- 
processing context. The code is an integer with one of the 


following values: 
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Code Meaning 


MSGF_ DIALOGBOX _ Processing messages inside 


Dialog Box 
MSGF_ MESSAGEBOX Processing messages inside 
MessageBox 
MSGF_ MENU Menu tracking 
The filter function can handle the message in one of three 
ways: 
1. Process the message and return nonzero. Windows 
will do no further processing of the message. 
2. Return zero without processing the message. Win- 
dows will perform the usual processing. 
3. Modify the message and return zero. Windows will 


Return Value 


Notes 


perform the usual processing on the modified mes- 
sage. 


loPrevFtlterF'unc is the address of the previously 
installed filter, if any. If the application chooses not 
to process a given message, it should call the previ- 
ously installed filter and pass it the message infor- 
mation. This allows a chain of filler functions to be 
created. 


The address passed as the lpFtlterFunc parameter 
must be created using MakeProclInstance. 


The filter function must use the Pascal calling con- 
vention and must be declared FAR. The number 
and type of the parameters depends on whether a 
STACKSIZE statement appears in the .DEF file for 
the application. For applications that use a 
STACKSIZE statement (SS==—DS), [pFilterFunc 


must be declared as follows: 


FilterFunc( wDummy, pMsg, nCode) : bProcess 


For applications that do not use a STACKSIZE 
statement (SS!=DS), lpFilterFunc must be declared 
as follows: 


FilterFunc( lpMsg, nCode ) : bProcess 
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3.1 Introduction 


This chapter describes the Graphics Device Interface (GDI) functions. 
These functions make up a special graphics package that provides access to 
a large variety of graphic and other display devices. 


3.2 Display Context Functions 


This section describes the functions used to create and destroy display con- 
texts for graphics devices. A display context is a set of data, maintained by 
GDI, that describes a graphics device and its device driver. 


CreateDC ( I[pDriverName, lpDeviceName, lpOutput, lpInitData ): hDC 


Purpose 


Parameters 


This function creates a display context for the specified 
device. The [pDriverName, lpDeviceName, and lpOutput 
parameters specify the device driver, device name, and phy- 
sical output medium (file or port). 


lpDriverName is a long pointer to a null-terminated ASCII 
string specifying the MS-DOS filename, without extension, 
of the device driver (for example, “EPSON” ). 


lpDeviceName is a long pointer to a null-terminated ASCII 
string specifying the name of the specific device to be sup- 
ported (for example, “EPSON FX-80”). This parameter is 
used if the module supports more than one device. 


lp Output is a long pointer to a null-terminated ASCII string 
specifying the MS-DOS file or device name for the physical 
output medium (file or output port). 


lnInitData is a long pointer to device-specific initialization 
data for the device driver. l[pInitData is NULL if the device 
driver requires no initialization. 


Return Value If the function is successful, hDC is a handle to a display 


Notes 


context for the specified device. Otherwise, ADC’ is NULL. 
MS-DOS device names follow MS-DOS conventions: an end- 


ing colon is recommended, but optional. Windows strips the 
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terminating colon so that a device name ending with a colon 
is mapped to the same port as the same name without a 
colon. 


The driver and port names must not contain leading or 
trailing spaces. 


CreateCompatibleDC ( ADC’): hMemDC 


Purpose 


Parameters 


Return Value 


Notes 


This function creates a memory display context that is com- 
patible with the device specified by ADC. A memory display 
context is a block of memory that represents a display sur- 
face. The memory display can be used to prepare images in 
memory before copying them to the actual display surface of 
the compatible device. 


When a memory display context is created, GDI automati- 
cally selects a monochrome stock bitmap for it. 


hDC is a handle to a display context. If ADC is NULL, the 
function creates a memory display context that is compati- 
ble with the system display. 


If the function is successful, AMemDC is a handle to a 
memory display context. Otherwise, it is NULL. 


This function can only be used to create compatible display 


contexts for devices that support raster operations. See the 
GetDeviceCaps function and the RC_ BITBLT capability. 


GDI output functions can be used with a memory display 
context only if a bitmap has been created and selected into 
that context. 


CreateIC ( [pDriverName, IpDeviceName, lpOutput, lpInitData ) : hIC 


Purpose 


Parameters 
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This function creates an information context for the 
specified device. The information context provides a fast 
way to get information about the device ae creating a 
display context. 


lpDriverName is a long pointer to a null-terminated ASCII 
string specifying the MS-DOS filename, without extension, 
of the device driver (for example, “EPSON?” ). 


lpDeviceName is a long pointer to a null-terminated ASCII 
string specifying the name of the specific device to be sup- 
ported (for example, “EPSON FX-80”). This parameter is 
used if the module supports more than one device. 
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lpOutput is a long pointer to a null-terminated ASCII string 
specifying the MS-DOS file or device name for the physical 
output medium (file or port). 


lpInitData is a long pointer to device-specific initialization 
data for the device driver. [pInitData is NULL if the device 
driver is to use the default initialization (if any) specified by 
the user through the control panel. 


Return Value If the function is successful, hJC is a handle to an informa- 


Notes 


tion context for the specified device. Otherwise, it is NULL. 


MS-DOS device names follow MS-DOS conventions: an end- 
ing colon is recommended, but optional. Windows strips the 
terminating colon so that a device name ending with a colon 
is pane to the same port as the same name without a 
colon. 


The driver and port names must not contain leading or 
trailing spaces. 


GDI output functions cannot be used with information con- 
texts. 


DeleteDC ( hDC'): bDeleted 


Purpose 


Parameters 
Return Value 


This function deletes the specified display context. If hDC is 
the last display context for a given device, the device is 
notified and all storage and system resources used by the 
device are released. 


hDC is a handle to a display context. 


bDeleted, a Boolean value, is nonzero if the display context is 
successfully deleted (regardless of whether the deleted 
display context is the last display context for the device). If 
an error occurs, bDeleted is zero. 


SaveDC ( ADC): nSavedDC 


Purpose 


Parameters 


This function saves the current state of the display context 
hDC by copying state information (such as clipping region, 
selected objects, and mapping mode) to a context stack. 
The saved display context can later be restored by using the 
RestoreDC function. 


hDC is a handle to the display context to be saved. 
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Return Value nSavedDC is a short integer value uniquely identifying the 


Notes 


saved display context. It is 0 if an error occurs. 


SaveDC can be used any number of times to save any 
number of display context states. 


RestoreDC ( ADC, nSavedDC ) : bRestored 


Purpose 


Parameters 


Return Value 


This function restores the display context specified by hDC 
to the previous state identified by nSavedDC. RestoreDC 
restores the context by copying state information saved on 
the context stack by earlier calls to SaveDC. 


The context stack can contain the state information for 
several display contexts. If the context specified by 
nSavedDC is not at the top of the stack, RestoreDC deletes 
any state information between nSavedDC and the top of the 
stack. The deleted information is lost. 


hDC is a handle to a display context. 


nSavedDC is a short integer value specifying the device con- 
text to be restored. It can be a value returned by a previous 
SaveDC call. If nSavedDC is —-1, the most recent display 
context saved is restored. 


bRestored, a Boolean value, is nonzero if the specified con- 
text is restored. Otherwise, it is zero. 


3.3 Output Functions 


This section describes the functions used to create images on a display sur- 


face. 


MoveTo ( hDC, X, Y): ptPrevPos 


Purpose 


Parameters 
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This function moves the current position to the point 


specified by X and Y. 
hDC is a handle to a display context. 


X and ¥Y are short integer values specifying the logical coor- 
dinates of the new position. 
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Return Value ptPrevPos is a long integer specifying the x and y coordi- 


Note 


nates of the previous position. The y coordinate is in the 
high-order word; the x coordinate is in the low-order word. 


Although MoveTo has no output, it affects other output 
functions that use the current position. 


GetCurrentPosition ( hDC'): ptPos 


Purpose 


Parameters 


This function retrieves the logical coordinates of the current 
position. 


hDC is a handle to a display context. 


Return Value ptPosis a long unsigned integer specifying the current posi- 


tion. The y coordinate is in the high-order word; the x coor- 
dinate is in the low-order word. 


LineTo ( ADC, X, Y): bDrawn 


Purpose 


Parameters 


This function draws a line from the current position up to, 
but not including, the point specified by X and Y. The line 
is drawn with the currently selected pen. If no error occurs, 
the current position is set to (X, Y). 


hDC is a handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the end point for the line. 


Return Value 6Drawn, a Boolean value, is nonzero if the line is drawn. 


Otherwise, it is zero. 


Polyline ( ADC, lpPoints, nCount ) : bDrawn 


Purpose 


Parameters 


This function draws a set of line segments, connecting the 
points specified by the [pPotnts parameter. The lines are 
drawn from the first point through subsequent points with a 
result as if the MoveTo and LineTo functions were used to 
move to each new point and connect it to the next. (How- 
ever, the current position is neither used nor updated by 
Polyline). 


hDC'is a handle to a display context. 


lpPoints is a long pointer to an array of points to be con- 
nected. Each element in the array must have POINT type. 
The x and y coordinates of the points are assumed to be log- 
ical coordinates. 
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nCount is a short integer value specifying the number of 
points in the array. It must be at least 2. 


Return Value 6Drawn, a Boolean value, is nonzero if the line segments are 


drawn. Otherwise, bDrawn is zero. 


Rectangle ( ADC, X1, Y1, X2, Y2): bDrawn 


Purpose 


Parameters 


Return Value 


Notes 


This function draws a rectangle. The interior of the rectan- 
gle is filled using the currently selected brush, and a border 
is drawn with the currently selected pen. 


hDC'is a handle to a display context. 


Xi and Yi are short integer values specifying the logical 
coordinates of the upper left corner of the rectangle. 


AX2and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the rectangle. 


bDrawn, a Boolean value, is nonzero if the rectangle is 
drawn. Otherwise, bDrawn is zero. 


The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 


The current position is neither used nor updated by this 
function. 


RoundRect ( ADC, X1, Y1, X2, Y2, X38, Y3): bDrawn 


Purpose 


Parameters 


This function draws a rectangle with rounded corners. The 
interior of the rectangle is filled using the currently selected 
brush, and a border is drawn with the currently selected 
pen. 


hDC is a handle to a display context. 


Xi and Y1 are short integer values specifying the logical 
coordinates of the upper left corner of the rectangle. 


A2and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the rectangle. 


X3and Y8 are short integer values specifying the width and 
height of the ellipse to be used to draw the rounded corners. 


Return Value bDrawn, a Boolean value, is nonzero if the rectangle is 
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drawn. Otherwise, bDrawn is zero. 


Notes 
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The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 


The current position is neither used nor updated by this 
function. 


Polygon ( ADC, lpPoints, nCount ): bDrawn 


Purpose 


Parameters 


This function draws a polygon consisting of two or more 
points (vertices) connected by lines. The lines are drawn 
according to the current polygon filling mode. In ALTER- 
NATE mode, lines are drawn from the first point through 
subsequent points using the current pen, and the interior is 
filled with the current brush. In WINDING mode, all points 
are used to compute a border, the border is then drawn 
using the current pen, and the interior filled with the 
current brush. (See the SetPolyFillMode for a description 
of how WINDING mode borders are computed.) In both 
modes, the polygon is automatically closed, if necessary, by 
drawing a line from the last vertex to the first. 


hDC is a handle to a display context. 


lpPoints is a long pointer to an array of points specifying the 
vertices of the polygon. Each point in the array must have 
POINT type. The x and y coordinates are assumed to be 
logical coordinates. 


nCount is a short integer value specifying the number of ver- 
tices given in the /pPotnts array. 


Return Value bDrawn, a Boolean value, is nonzero if the function is suc- 


Notes 


cessful. Otherwise, it is zero. 


The current position is neither used nor updated by this 
function. 


The current polygon filling mode can be retrieved or set 
using the GetPolyFillMode and SetPolyFillMode func- 
tions. , 


Ellipse ( ADC, X1, Y1, X2, Y2): bDrawn 


Purpose 


This function draws an ellipse. The center of the ellipse is 
the center of the bounding rectangle specified by X1, Y1, 
A2, and Y2. The ellipse border is drawn with the current 
pen, and the interior is filled with the current brush. 


If the bounding rectangle is empty, nothing is drawn. 
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Parameters 


Return Value 


Notes 


hDC is a handle to a display context. 


X1 and Yi are short integer values specifying the logical 
coordinates of the upper left corner of the bounding rectan- 
gle. 


X2 and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the bounding rectan- 
gle. 


bDrawn, a Boolean value, is nonzero if the ellipse is drawn. 
Otherwise, bDrawn is zero. 


The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32K units. 


The current position is neither used nor updated by this 
function. 


Arc ( hDC, X1, Y1, X2, Y2, X8, Y8, X4, Y4): bDrawn 


Purpose 


Parameters 


This function draws an elliptical arc. The center of the arc 
is the center of the bounding rectangle specified by the 
points X1, Y1 and X2, Y2. The arc starts at the point X93, 
Y3 and ends at the point X4, Y4. The arc is drawn using 
the currently selected pen moving in a counterclockwise 
direction. Since an arc does not define a closed area, it is 


not filled. 
hDC is a handle to a display context. 


X1 and Y1 are short integer values specifying the logical 
coordinates of the upper left corner of the bounding rectan- 


gle. 


X2 and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the bounding rectan- 
gle. 


X3 and Y3 are short integer values specifying the logical 
coordinates of the arc’s starting point. This point does not 
have to lie exactly on the arc. 


X4 and Y4 are short integer values specifying the logical 
coordinates of the arc’s endpoint. This point does not have 
to lie exactly on the arc. 


Return Value 6Drawn, a Boolean value, is nonzero if the arc is drawn. 
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Otherwise, it is zero. 


Notes 
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The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 


Pie ( ADC, X1, Y1, X2, Y2, X83, Y3, X4, Y4): bDrawn 


Purpose 


Parameters 


Return Value 


Notes 


This function draws an pie-shaped wedge by drawing an 
elliptical arc whose center and two endpoints are joined by 
lines. The center of the arc is the center of the bounding 
rectangle specified by X1, Y1, X2, and Y2. The starting and 
ending points of the arc are specified by X8, Y3, X4, and Y4. 
The arc is drawn with the currently selected pen moving in a 
counterclockwise direction. Two additional lines are drawn 
from each endpoint to the arc’s center. The pie-shaped area 
is filled with the currently selected brush. 


ADC is a handle to a display context. 


X1 and Yi are short integer values specifying the logical 
coordinates of the upper left corner of the bounding rectan- 
gle. 


X2and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the bounding rectan- 
gle. 


X38 and Y3 are short integer values specifying the logical 
coordinates of the starting point of the arc. This point does 
not have to lie exactly on the arc. 


X4 and Y4 are short integer values specifying the logical 
coordinates of the endpoint of the arc. This point does not 
have to lie exactly on the arc. 


bDrawn, a Boolean value, is nonzero if the pie shape is 
drawn. Otherwise, it is zero. 


The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 


The current position is neither used nor updated by this 
function. 


PatBlt ( ADC, X, Y, nWidth, nHeight, dwRop ): bDrawn 


Purpose 


This function creates a bit pattern on the specified device. 
The pattern is a combination of the currently selected brush 
and the pattern already on the device. The raster opera- 
tion code, dwRop, defines how the patterns are to be com- 
bined. 
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Parameters 


hDC is a handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the upper left corner of the rectangle to receive 
the pattern. 


nWidth and nHetght are short integer values specifying the 
width and height (in logical units) of the rectangle to receive 
the pattern. 


dwRop is a long unsigned integer specifying the raster opera- 
tion code. 


Return Value bDrawn, a Boolean value, is nonzero if the bit pattern is 


Note 


drawn. Otherwise, 6Drawn is zero. 


dwkop values for this function are a limited subset of the 
full 256 ternary raster operation codes; in particular, no 
operation code that refers to a source can be used. 


Not all devices support the PatBlt function. See the Get- 
DeviceCaps function and the RC_ BITBLT capability. 


BitBlt ( hDestDC, X, Y, nWidth, nHetght, hSrcDC, XSrc, YSrc, dwRop ) 


Purpose 


Parameters 
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This function moves a bitmap from the source device given 
by ASrcDC to the destination device given by hDestDC. The 
XSrce and YSrc parameters specify the origin on the source 
device of the bitmap to be moved. The X, Y, nWidth, and 
nHetght parameters specify the origin, width, and height of 
the rectangle on the destination device to be filled by the 
bitmap. The raster operation, dwRop, defines how the bits of 
the source and destination are combined. 


hDestDC is a handle to a display context for the destination 
device. 


X and Y are short integer values specifying the logical coor- 
dinates of the upper left corner of the destination rectangle. 


nWidth and nHetght are short integer values specifying the 
width and height in logical units of the destination rectangle 
and source bitmap. 


hSrcDC is a handle to a display context for the source 
device. It must be NULL if dwRop specifies a raster opera- 
tion that does not include a source. 


XSre and YSre are short integer values specifying the logical 
coordinates of the upper left corner of the source bitmap. 


Return Value 


Notes 
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dwhop is a long unsigned integer value specifying the raster 
operation to be performed. 


bDrawn, a Boolean value, is nonzero if the bitmap is drawn. 
Otherwise, bDrawn is zero. 


GDI transforms the nWidth and nHeight once using the des- 
tination display context, and once using the source display 
context. If the resulting extents do not match, GDI uses 
StretchBit to compress or stretch the source bitmap as 
necessary. 


If destination, source, and pattern bitmaps do not have the 
same color format, BitBlt converts the source and pattern 
bitmaps to match the destination. The foreground and 
background colors of the destination are used in the conver- 
sion. 


If BitBlt converts monochrome bitmaps to color, it sets 
white bits (1) to background color and black bits (0) to fore- 
ground color. To convert color to monochrome, the func- 
tion sets pixels that match the background color to white 
(1), and all other pixels to black (0). The foreground and 
background colors of the display context with color are 
used. 


Not all devices support the BitBlt function. See the Get- 
DeviceCaps function and the RC_ BITBLT capability. 


StretchBlt ( ADestDC, X, Y, nWidth, nHetght, hSrcDC, XSrc, YSrc, 


Purpose 


nSrcWidth, nSrcHeight, dwRop ): bDrawn 


This function moves a bitmap from a source rectangle into a 
destination rectangle, stretching or compressing the bitmap, 
if necessary, to fit the dimensions of the destination rectan- 
gle. StretchBlt uses the stretching mode of the destination 
display context (set by SetStretchBltMode) to determine 
how to stretch or compress the bitmap. 


StretchBlt moves the bitmap from'the source device given 
by hSrcDC to the destination device given by hDestDC. The 
ASre, YSrce, nSrcWidth, and nSrcHeight parameter define the 
origin and dimensions of the source rectangle. The X, Y, 
nWidth, and nHeight parameters give the origin and dimen- 
sions of the destination rectangle. The raster operation, 
dwkop, defines how the source bitmap and the bits already 
on the destination device are combined. 


StretchBlt creates a mirror image of a bitmap if the signs 
of the nSreWidth and nWidth or nSrcHeight and nHeight 
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Parameters 


differ. If nSrcWidth and nWidth have different signs, the 
function creates a mirror image of the bitmap along the x- 
axis. If nSrcHetght and nHeight have different signs, the 
function creates a mirror image of the bitmap along the y- 
axis. 


hDestDC is a handle to a display context for the destination 
device. 


X and Y are short integer values specifying the logical coor- 
dinates of the upper left corner of the destination rectangle. 


nWidth and nHezght are short integer values specifying the 
width and height in logical units of the destination rectan- 
gle. 


hSrcDC is a handle to a display context for the source 
device. 


ASre and YSrc are short integer values specifying the logical 
coordinates of the upper left corner of the source rectangle. 


nSrcWidth and nSrcHetght are short integer values specify- 
ing the width and height in logical units of the source rect- 
angle. 


dwHop is a long unsigned integer specifying the raster opera- 
tion code. 


Return Value bDrawn, a Boolean value, is nonzero if the bitmap is drawn. 


Notes 
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Otherwise, Drawn is zero. 


StretchBlt stretches or compresses the source bitmap in 
memory, then copies the result to the destination. If a pat- 
tern is to be merged with the result, it is not merged until 
the stretched source bitmap is copied to the destination. 


If a brush is used, it is the currently selected brush in the 
destination display context. 


The destination coordinates are transformed according to 
the destination display context; the source coordinates are 
transformed using the source display context. 


If destination, source, and pattern bitmaps do not have the 
same color format, StretchBlt converts the source and pat- 
tern bitmaps to match the the destination. The foreground 
and background colors of the destination are used in the 
conversion. 


If StretchBlt must convert a monochrome bitmap to color, 
it sets white bits (1) to background color and black bits (0) 
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to foreground color. To convert color to monochrome, it 
sets pixels that match the background color to white 1), 
and all other pixels to black (0). The foreground and back- 
ground colors of the color display context are used. 


Not all devices support the StretchBlt function. See the 
GetDeviceCaps function and the RC_ BITBLT capability. 


TextOut ( ADC, X, Y, lpString, nCount ): bDrawn 


Purpose 


Parameters 


Return Value 


Notes 


This function writes a character string on the specified 
display, using the currently selected font. The starting posi- 
tion of the string is given by the X and Y parameters. 


hDC'is a handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the starting point of the string. 


lnString is a long pointer to the character string to be 
drawn. 


nCount is a short integer value specifying the number of 
characters in the string. 


bDrawn, a Boolean value, is nonzero if the string is drawn. 
Otherwise, bDrawn is zero. 


Character origins are defined to be at the upper left corner 
of the character cell. 


The current position is not used or updated by this function. 


DrawText ( ADC, IpString, nCount, lpRect, wFormat ) 


Purpose 


Parameters 


This function draws formatted text in the rectangle specified 
by lpRect. The text is drawn using the currently selected 
text color and background color in the display context given 
by ADC. The output is clipped to the rectangle specified by 
lpRect (unless the DT_ NOCLIP format is used). 


A carriage return character returns the pen to the left edge 
of the rectangle, and a line feed character moves the pen 


down one line (unless the DT_ SINGLELINE format is used). 


Carriagé return/line feed sequences cause the line to wrap. 
hDC is a handle to a display context. 


lpString is a long pointer to the character string to be 
drawn. 
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nCount is a short integer value specifying the number of 
bytes in the string. If nCount is —-1, then IpString is assumed 
to be a long pointer to a null-terminated string. 


lnRect is a long pointer to a data structure having RECT 
type. The rectangle structure specifies the clipping rectan- 
gle in logical coordinates. 


wFormat is an integer value specifying the method of for- 
matting the text. It can be any combination of the follow- 
ing: 


Value Meaning 


DT_ LEFT Left justified text. 


DT_ CENTER 
Centered text. 


DT_RIGHT Right justified text. 
DT_ SINGLELINE 


Single line only. Carriage returns and 
line feeds do not break the line. 


DT_ TOP Top justified (single line only). 


DT_ VCENTER 
Vertically centered (single line only). 


DT_ BOTTOM 
Bottom justified (single line only). 


DT_ WORDBREAK 
Word breaking. Lines are automatically 
broken between words if a word would 
extend past the edge of the rectangle 
specified by /pRect. Carriage return/line 
feed sequences also cause a line break. 


DT_ EXPANDTABS : 
Expand tab characters (default number 
of characters per tab is 8). 


DT_ TABSTOP 
Set tab stops. The high-order byte of 
wFormat is the number of characters for 
each tab. Default is 8. 
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DT_NOCLIP Draw without clipping. DrawText is 
somewhat faster when D'T_ NOCLIP is 


used. 


DT_ EXTERNALLEADING 
Include the font external leading in line 
height. Normally, external leading is not 
included in the height of a line of text. 


The values can be combined with the bitwise OR operator. 


Return Value None. 


Note 


If the current font is too large for the specified rectangle, the 
function will not attempt to substitute a smaller font. 


GrayString ( ADC, hBrush, lpOutputFunc, lpData, nCount, X, Y, nWidth, 


Purpose 


Parameters 


nHetght ): bDrawn 


This function writes and grays a character string. The 
string is grayed regardless of the currently selected brush 
and background. 


hDC is a handle to a display context. 
hBrush is a handle to the brush to be used for graying. 


lpOutputFunc is a long pointer to a function to draw the 
string. If lpOutputF'unc is NULL, GDI uses the TextOut 
function, and /pData is assumed to be a long pointer to the 
character string to be output. If the characters to be output 
cannot be handled by TextOut (for example, the string is 
stored as a bitmap), the application must supply its own 
output function. 


lpData is a long pointer to data to be passed to the output 
function. If lpOutputF'unc is NULL, [pData must be a long 
pointer to the string to be output. 


nCount is a short integer specifying, the number of charac- 
ters to be output. If nCount is zero, GrayString calculates 
the length of the string (assuming that [pData is a pointer to 
the string). If nCount is —1 and the function pointed to by 
lp OutputF'unc returns zero, the image is shown but not 
grayed. 


X and Y are short integer values specifying the x and y coor- 
dinates (in logical units) of the starting position of the rect- 
angle enclosing the string. 
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nWedth and nHeight are short integer values specifying the 
width and height (in logical units) of the rectangle enclosing 
the string. If either nWidth or nHetght is zero, GrayString 
calculates the dimensions of the area (assuming [pData is a 
pointer to the string). 


Return Value bDrawn, a Boolean value, is nonzero if the string is drawn. 


Notes 


A return value of zero means that one of the following errors 
occurred: 


e The application-supplied output function returned 
zero. 
e TextOut returned zero. 
e Insufficient memory was available to create a 
memory bitmap for graying. 
The address passed as the [pOutputF'unc parameter must be 
created using MakeProclInstance. 
The function pointed to by lpOutputFunc must have the 
form: 
lpOutputFunc (hDC, lpData, nCount) : bSuccess 
where ADC, IpData, and nCount are the same as the parame- 
ters by the same name passed to GrayString. 


The return value, a Boolean value, must be nonzero to indi- 
cate success, and zero if an error occurs. 


Drawlcon ( hDC, X, Y, hIcon): bDrawn 


Purpose 


Parameters 


Return Value 
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This function draws an icon on the specified display, placing 
the icon’s upper left corner at the location specified by X 


and Y. 
hDC'is a handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the upper left corner of the icon. 


hIcon is a handle to an icon resource. The resource must 
have been previously loaded (using LoadIcon). 


6bDrawn, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is 0. 
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SetPixel ( hDC, X, Y, rgbColor ) : rgbActualColor 


Purpose This function sets the pixel at the point specified by X and Y 
to the closest approximation to the color specified by 
rgbColor. The point must be in the clipping region. If the 
point is not in the clipping region, the function is ignored. 


Parameters hDC'is a handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the point to be set. 


rgbColor is an RGB color value specifying the color to paint 
the point. 


Return Value rgbActualColor is an RGB color value specifying the color 
that the point is actually painted. This value can be 
different than rgbColor if an approximation of that color is 
used. If the function fails, e.g., the point is outside of clip- 
ping region, rgbActualColor is -1. 


Note Not all devices support the SetPixel function. See the Get- 
DeviceCaps function and the RC_BITBLT capability. 


GetPixel ( ADC, X, Y): rgbColor 


Purpose This function retrieves the RGB color value of the pixel at 
the point specified by X and Y. The point must be in the 
clipping region. If the point is not in the clipping region, 
the function is ignored. 


Parameters hDC isa handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the point to be examined. 


Return Value If the function is successful, rgbColor, an RGB color value, is 
the color of the given point. It is —1 if the coordinates do 
not specify a point in the clipping region. 


Note Not all devices support the GetPixel function. See the 
GetDeviceCaps function and the RC_ BITBLT capability. 
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FloodFill ( hDC, X, Y, rgbColor ) : 6Filled 


Purpose 


Parameters 


Return Value 


Note 


This function fills an area of the display surface with the 
current brush. The area is assumed to be bounded by the 
given rgbColor. The function begins at the point specified 
by X and Y and continues in all directions to the color 
boundary. 


hDC is a handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the point to begin filling. 


rgbColor is an RGB color value specifying the color of the 
boundary. 


billed, a Boolean value, is nonzero if the function is success- 
ful. It is zero if the filling could not be completed, the given 
point has the boundary color rgbColor, or the point is out- 
side the clipping region. 


Not all devices support the FloodF ill function. See the 
GetDeviceCaps function and the RC_ BITBLT capability. 


LineDDA ( X1, Y1, X2, Y2, lpLineF unc, lpData ) 


Purpose 


Parameters 


This function computes all successive points in the line 
starting at the point specified by X17 and Y1 and ending at 
the point specified by X2 and Y2. The end point is not 
included as part of the line. For each point on the line, 
LineDDA calls the application-supplied function pointed to 
by lpLineF unc, passing to the function the coordinates of 
the current point and the /pData parameter. 


X1 and Y1 are short integer values specifying the logical 
coordinates of the first point. 


X2 and Y2 are short integer values specifying the logical 
coordinates of the last point. 


lpLineFunc is a long pointer to an application-supplied func- 
tion. 


lpData is a long pointer to application-supplied data. 


Return Value None. 
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The application-supplied function must have the form: 
lpLineFunc(X, Y, lpData) 


where X and Y are short integer coordinates of the current 
point, and /pData is a long pointer to the application- 
supplied data. The function can perform any task. It has 
no return value. 


FillRgn ( ADC, hRgn, hBrush ): bFilled 


Purpose 


Parameters 


Return Value 


This function fills the region specified by hRgn with the 
brush specified by ABrush. 


hDC is a handle to a display context. 
hRgn is a handle to a region to be filled. 
hBrush is a handle to the brush to be used to fill the region. 


bFilled, a Boolean value, is nonzero if the function is success- 
ful. Otherwise, it is zero. 


FrameRgn ( ADC, hRgn, hBrush, nWidth, nHeight ): bFramed 


Purpose 


Parameter 


Return Value 


This function draws a border around the region specified by 
hftgn, using the brush specified by hBrush. The nWidth 
parameter specifies the width of the border on vertical brush 
strokes; nHeight specifies the height on horizontal strokes. 


hDC'is a handle to a display context. 
hign is a handle to a region to be enclosed in a border. 


hBrush is a handle to the brush to be used to draw the 
border. 


n Width is a short integer number specifying the width of 
vertical brush strokes. 


nHeight is a short integer number specifying the height of 
horizontal brush strokes. 


bF'ramed, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 
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InvertRgn ( hDC, hRgn ): binverted 


Purpose This function inverts the colors in the region specified by 


hRgn. 
Parameters hDC'is a handle to a device context containing the region. 
hRgn is a handle to a region to be filled. 


Return Value bInverted, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


PaintRgn ( ADC, hRgn ): bFilled 


Purpose This function fills the region specified by hRgn with the 
currently selected brush. 


Parameters hDC isa handle to a device context containing the region. 
hRgn is a handle to a region to be filled. 


Return Value 6Filled, a Boolean value, is nonzero if the function is success- 
ful. Otherwise, it is zero. 


FillRect ( ADC, lpRect, hBrush ) 


Purpose This function fills a given rectangle using the specified 
brush. 


Parameters hDCisahandle to a display context. 
lpRect is a long pointer toa RECT data structure. 
hBrush is a handle to a brush used to fill the rectangle. 


Return Value None. 


FrameRect ( ADC, lpRect, hBrush ) 


Purpose This function draws a border for the rectangle whose logical 
coordinates are pointed to by /pRect. The function uses the 
specified brush to draw the border. 


Parameters hDC isa handle to a display context. 


lpRect is a long pointer to a data structure having RECT 
type. The structure must contain the logical coordinates of 
the upper left and lower right corners of the rectangle. 
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hBrush is a handle to a brush to be used for framing the 
rectangle. 


Return Value None. 


InvertRect ( hDC, lpRect ) 


Purpose This function inverts the display bits of the specified rectan- 
gle. 

Parameters hDC isa handle to a display context. 
lpRect is a long pointer to a data structure having RECT 
type. 

Return Value None. 


3.4 Drawing Object Functions 


This section describes the functions used to create drawing objects. Draw- 
ing objects are used by GDI to create images on the display surface. They 
include pens, brushes, bitmaps, and fonts. Regions, also described in this 
section, are special objects that represent areas to draw instead of a style or 
color in which to draw an image. 


GetStockObject ( nIndez ) : hObject 


Purpose This function retrieves a handle to one of the several 
predefined stock pens, brushes, or fonts. 


Parameters nindexis a short integer value specifying the type of stock 
object desired. It can be any one of the following: 


Value Stock Object 
WHITE_ BRUSH White Brush 
LTGRAY_ BRUSH Light Gray Brush 
GRAY_- BRUSH Gray Brush 
DKGRAY_ BRUSH Dark Gray Brush 
BLACK BRUSH Black Brush 


HOLLOW_ BRUSH Hollow Brush 
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NULL_ BRUSH Null Brush 
WHITE_ PEN White Pen 
BLACK PEN Black Pen 

NULL_ PEN Null Pen 


ANSI FIXED_FONT ANSI Fixed System Font 
OEM_ FIXED. FONT OEM-dependent Fixed Font 
ANSL VAR_ FONT ANSI Variable System Font 
SYSTEM_ FONT System-dependent Fixed Font 
DEVICE_ DEFAULT_ FONT 


Device-dependent Font 


Return Value If the function is successful, hObject is a handle to the logical 


Notes 


object. Otherwise, it is NULL. 


The LTGRAY_ BRUSH, GRAY_ BRUSH, and 

DKGRAY_ BRUSH objects should not be used as a back- 
ground brush or for any other purpose in a window whose 
class does not specify CS_ VREDRAW and CS_ HREDRAW 
styles. Using a gray stock brush in such windows can lead 
to misalignment of brush patterns after a window is moved 
or sized. Stock brush origins cannot be adjusted (see the 
SetBrushOrg function). 


CreatePen ( nPenStyle, nWidth, rgbColor ): hPen 


Purpose 


Parameters 
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This function creates a logical pen having the specified style, 
width, and color. The pen can be subsequently selected as 
the current pen for any device. 


nPenStyle is a short integer value specifying the pen style. 
It can be any one of the following: 


GDI Functions 


Value Pen Style 


0 Solid 

1 Dash 

2 Dot 

3 Dash and dot 

4 Dash and two dots 

5 Null 
n Width is a short integer value specifying the width of the 
pen in logical units. 


rgbColor is an RGB color value specifying the color of the 
pen. 


Return Value If the function is successful, hPen is a handle to a logical 


Note 


pen. Otherwise, it is NULL. 


Pens with a physical width greater than 1 will always have 
either null or solid style. 


CreatePenIndirect ( lpLogPen ) : hPen 


Purpose 


Parameters 


This function creates a logical pen having the style, width, 
and color given in the data structure pointed to by [pLog- 
Pen. 


lnLogPen is a long pointer to a data structure having LOG- 
PEN type. 


Return Value If the function is successful, hPen is a handle to a logical pen 


Note 


object. Otherwise, it is NULL. 


Pens with a physical width greater than 1 will always have 
either null or solid style. 


CreateSolidBrush ( rgbColor ) : ABrush 


Purpose 


Parameters 


This function creates a logical brush having the specified 
solid color. The brush can be subsequently selected as the 
current brush for any device. 


rgbColor is an RGB color value specifying the color of the 
brush. 
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Return Value If the function is successful, hBrush is a handle to a logical 


brush. Otherwise, it is NULL. 
CreateHatchBrush ( n/ndez, rgbColor ) : hBrush 


Purpose This function creates a logical brush having the specified 
hatched pattern and color. The brush can be subsequently 
selected as the current brush for any device. 


Parameters nindezxis a short integer value specifying the hatch style of 
the brush. It can be any one of the following: 


Value Hatch Style 

HS— HORIZONTAL horizontal hatch 

HS_ VERTICAL vertical hatch 

HS_ FDIAGONAL 45-degree upward hatch from 
left to right 

HS— BDIAGONAL 45-degree downward hatch 
from left to right 

HS_ CROSS horizontal and vertical cross- 
hatch 

HS_ DIAGCROSS 45-degree cross-hatch 


rgbColor is an RGB color value specifying the foreground 
color of the brush; that is, the color of the hatches. 


Return Value If the function is successful, hBrush is a handle to a logical 


brush. Otherwise, it is NULL. 


CreatePatternBrush ( hBitmap ): hBrush 


Purpose This function creates a logical brush with the pattern 
specified by hBitmap. The brush can be subsequently 
selected as the current brush for any device that supports 
raster operations (see the GetDeviceCaps routine and the 


RC_ BITBLT capability). 


Parameters hBtitmap isa handle to a bitmap. It is assumed to have been 
created using the CreateBitmap, CreateBitmapIn- 
direct, or CreateCompatibleBitmap, function. The 
minimum size for a bitmap to be used in a fill pattern is 
8 by 8. 
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Return Value If the function is successful, hBrush is a handle to a logical 


Note 


brush. Otherwise, it is NULL. 


A pattern brush can be deleted with the DeleteObject 
function without affecting the associated bitmap. This 
means the bitmap can be used to create any number of pat- 
tern brushes. 


CreateBrushIndirect ( [pLogBrush ): hBrush 


Purpose 


Parameters 


This function creates a logical brush having the style, color, 
and pattern given in the data structure pointed to by lpLog- 
Brush. The brush can be subsequently selected as the 
current brush for any device. 


lpLogBrush is a long pointer to a data structure having 
LOGBRUSH type. 


Return Value If the function is successful, hBrush is a handle to a logical 


brush. Otherwise, it is NULL. 


CreateBitmap ( nWidth, nHeight, nPlanes, nBitCount, lpBits ) : hBitmap 


Purpose 


Parameters 


This function creates a bitmap having the specified width, 
height, and bit pattern. The bitmap can subsequently be 
selected as the current bitmap for a memory display using 
the SelectObject function. The memory display must have 
a compatible planes/pixels format. 


Although a bitmap cannot be copied directly to a display 
device, the BitBlt function can copy it from a memory 
display context in which it is the current bitmap to any 
compatible device. 


n Width is a short integer value specifying the width in pixels 
of the bitmap. 


nHerght is a short integer value specifying the height in pix- 
els of the bitmap. 


nPlanes is a short integer value specifying the number of 


color planes in the bitmap. Each plane has 
nWidth+xnHeight+nBitCount bits. 


nBitCount is a short integer value specifying the number of 
color bits per display pixel. 


lpBits is a long pointer to a short integer array containing 
the initial bitmap bit values, or it is the long integer value 0 
specifying an uninitialized bitmap. 
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Return Value If the function is successful, hBitmap is a handle to a bitmap. 


Otherwise, it is NULL. 


CreateBitmapIndirect ( [pBitmap ) : hBitmap 


Purpose 


Parameters 


This function creates a bitmap having the width, height, 
and bit pattern given in the data structure pointed to by 
lp Bitmap. 


Although a bitmap cannot be directly selected for a display 
device, it can be selected as the current bitmap for a 
memory display and copied to any compatible display device 
by using the BitBlt function. 


lpBitmap is a long pointer to a data structure having BIT- 
MAP type. 


Return Value If the function is successful, hBitmap is a handle to a bitmap. 


Otherwise, it is NULL. 


CreateCompatibleBitmap ( ADC, nWidth, nHetght ) : hBitmap 


Purpose 


Parameters 


1382 


This function creates a bitmap that is compatible with the 
device specified by ADC. The bitmap has the same number 
of color planes or bits per pixel format as the specified 
device. It can be selected as the current bitmap for any 
memory display that is compatible with ADC. 


If ADC is a memory display context, the bitmap returned 
has the same format as the currently selected bitmap in that 
display context. 


When a memory display context is created, GDI automati- 
cally selects a monochrome stock bitmap for it. 


Since a color memory display context can have either color 
or monochrome bitmaps selected, the format of the bitmap 
returned by CreateCompatibleBitmap is not always the 
same; however, the format of a compatible bitmap for a 
non-memory display context is always in the format of the 
device. 


ADC is a handle to a display context. 


n Width is a short integer value specifying the width in bits 
of the bitmap. 


nHetght is a short integer value specifying the height in bits 
of the bitmap. 
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Return Value If the function is successful, hBttmap is a handle to a bitmap. 
Otherwise, it is NULL. 
SetBitmapBits ( hBitmap, dwCount, IpBits ) : dwCopied 


Purpose This function sets the bits of a bitmap to the bit values 
given by [pBits. 


Parameters hBitmap is a handle to the bitmap to be set. 


dwCount is an unsigned long integer value specifying the 
number of bytes pointed to by [pBits. 


lpBits is a long pointer to a short integer array of bits. 


Return Value dwCopited, an unsigned long integer value, specifies the 
number of bytes actually copied. 


GetBitmapBits ( hBitmap, dwCount, lpBits ) : dwCopted 


Purpose This function copies the bits of the specified bitmap into the 
buffer pointed to by [pBits. The dwCount parameter 
specifies the number of bytes to copy to the buffer. The 
GetObject function should be used to determine the 
correct dwCount value for the given bitmap. 


Parameters hBttmap is a handle to a bitmap. 


dwCount is an unsigned long integer value specifying the 
number of bytes to be copied. 


lpBits is a long pointer to the buffer to receive the bitmap. 
The bitmap is an array of short integers. 


Return Value dwCopied, an unsigned long integer value, is the actual 
number of bytes in the bitmap. It is 0 if there is an error. 
SetBitmapDimension ( hBttmap, X, Y ) : ptOldDimenstons 


Purpose This routine associates a width and height to a bitmap in 
0.1 millimeter units. These values are not used internally by 
GDI, GetBitmapDimension can be used to retrieve them. 


Parameters hBitmap is a handle to a bitmap. 


X is a short integer specifying the width of the bitmap in 0.1 
millimeter units. 


Y is a short integer specifying the height of the bitmap in 
0.1 millimeter units. 
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Return Value ptOldDimenstons is a long integer value specifying the previ- 


ous bitmap dimensions. The height is in the high-order 
word, width is in the low-order word. 


GetBitmapDimension ( hBitmap ) : ptDimensions 


Purpose 


Parameters 


This routine returns the width and height of the bitmap 
specified by hBttmap. The height and width is assumed to 
have been previously set using the SetBitmapDimension 
function. 


hBitmap is a handle to a bitmap. 


Return Value ptDimensions is a long integer value specifying the width and 


CreateF ont ( 


Purpose 


Parameters 
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height of the bitmap in 0.1 millimeter units. The height is 
in the high-order word, width is in the low-order word. If 
the bitmap width and height have not been set using Set- 
BitmapDimension, ptDimensions is zero. 


nHerght, nWidth, nEscapement, nOrtentation, nWeight, 
cltalic, cUnderline, cStrikeOut, nCharSet, nOutputPrecision, 
nClipPreciston, cQuality, cPttchAndF amily, lpFacename ) 

: hFont 


This function creates a logical font having the specified 
characteristics. The logical font can subsequently be 
selected as the current font for any device. 


nHeight is a short integer value specifying the desired height 
(in logical units) of the font. The height of a font can be 
specified in three ways. If nHezght is greater than zero, it is 
transformed into device units and matched against the cell 
height of the available fonts. If nHetght is zero, a reasonable 
default size is used. If nHezght is less than zero, it is 
transformed into device units and the absolute value is 
matched against the character height of the available fonts. 
For all height comparisons, the font mapper looks for the 
largest font which does not exceed the requested size, and if 
there is no such font, looks for the smallest font available. 


n Width is a short integer value specifying the average width 
of characters in the font in logical units. If nWidth is zero, 
the aspect ratio of the device will be matched against the 
digitization aspect ratio of the available fonts looking for 
the closest match by absolute value of the difference. 


nEscapement is a short integer value specifying the angle (in 
tenths of degrees) of each line of text written in the font 
(relative to the bottom of the page). 
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nOrientation is a short integer value specifying the angle (in 
tenths of degrees) of each character’s baseline relative to the 
bottom of the page. 


nWezght is a short integer value specifying the desired 
weight of the font in the range 0 to 1000 (for example, 400 is 
normal, 700 is bold). If 0, a default weight is used. 


cltaltc is an 8-bit flag specifying whether or not the font is 
italic. 


cUnderline is an 8-bit flag specifying whether or not the font 
is underlined. 


cStrikeOut is an 8-bit flag specifying whether or not charac- 
ters in the font are struck out. 


nCharSet is a short integer value specifying the desired char- 
acter set. It can be one of the following: 


ANSL CHARSET Windows standard ANSI character set 
OEM_ CHARSET System-specific character set 


nOutputPreciston is a short integer value specifying the 
desired output precision. It can be any one of the following: 


OUT_ DEFAULT_ PRECIS 
OUT_STRING_ PRECIS 
OUT_ CHARACTER_ PRECIS 
OUT_STROKE_ PRECIS 


nClipPrectston is a short integer value specifying the desired 
clipping precision. It can be any one of the following: 


CLIP_ DEFAULT_ PRECIS 
CLIP_ CHARACTER_ PRECIS 
CLIP_STROKE_ PRECIS 


cQuality is an 8-bit flag specifying the desired output qual- 
ity. It can be any one of the following: 
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Value 
PROOF_ QUALITY 


DRAFT_ QUALITY 


DEFAULT_ QUALITY 


Meaning 


The character quality of the 
font is more important than 
exact matching of the logical 
font attributes. For GDI fonts, 
scaling is disabled and the font 
closest in size is chosen. 
Although the chosen font size 
may not be mapped exactly 
when PROOF_ QUALITY is 
used, the quality of the font is 
high and there is no degrada- 
tion of appearance. Bold, 
italic, underline, and strikeout 
are synthesized if needed. 


The appearance of the font is 
less important than if 
PROOF_ QUALITY is used. 
For GDI fonts, scaling is 
enabled, with the result that 
more font sizes are available, 
but the quality may be lower. 
Bold, italic, underline, and 
strikeout are synthesized if 
needed. 


The appearance of the font 
does not matter. 


cPitchAndF amily is an 8-bit flag specifying the font pitch 
and family. The low 2 bits specify the pitch of the font and 
can be any one of the following: 


DEFAULT_ PITCH 
FIXED_ PITCH 
VARIABLE_ PITCH 


The four high-order bits of the field specify the font family 
and can be any one of the following: 
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FF_ DONTCARE 
FF_ ROMAN 
FF_SWISS 

FF_ MODERN 

FF_ SCRIPT 

FF_ DECORATIVE 


lpFacename is a long pointer to a null-terminated ASCII 
string specifying the facename of the font. The Enum- 
Fonts function can be used to enumerate the facenames of 
all currently available fonts. 


Return Value If the function is successful, hF ont is a handle to a logical 


Notes 


font. Otherwise, it is NULL. 


CreateF ont creates a logical font having all the specified 
characteristics. When the font is selected using SelectOb- 
ject, GDI’s font mapper attempts to match the logical font 
with an existing physical font. If it fails to find an exact 
match, it provides an alternate whose characteristics match 
as many of the requested characteristics as possible. See the 
Windows Programming Gutde for a description of the font 
mapper. 


CreateFontIndirect ( [pLogFont ): hFont 


Purpose 


Parameters 


This function creates a logical font having the characteris- 
tics given in the data structure pointed to by [pLogFont. 
The font can be subsequently selected as the current font for 
any device. 


lyLogFont is a long pointer to a data structure having 
LOGFONT type. 


Return Value If the function is successful, hFont is a handle to a logical 


Notes 


font. Otherwise, it is NULL. 


CreateF ontIndirect creates a logical font having all the 
specified characteristics. When the font is selected using 
SelectObject, GDI’s font mapper attempts to match the 
logical font with an existing physical font. If it fails to find 
an exact font, it provides an alternate whose characteristics 
match as many of the requested characteristics as possible. 
See the Windows Programming Guide for a description of the 
font mapper. 
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DeleteObject ( hObject ): bDeleted 


Purpose 


Parameters 


Return Value 


Notes 


This function deletes a logical pen, brush, font, bitmap, or 
region from memory by freeing all system storage associated 
with the object. After deletion, the handle hObject is no 
longer valid. 


hObject is a handle to a logical pen, brush, font, bitmap, or 
region. 


bDeleted, a Boolean value, is nonzero if the specified object is 
deleted. It is zero if hObject is not a valid handle or is 
currently selected into a display context. 


The object to be deleted should not be currently selected in 
a display context, unless the display context is deleted 
before the object is deleted. 


When a pattern brush is deleted, the bitmap associated with 
the brush is not deleted. The bitmap must be deleted on its 
own. 


3.5 Selection Functions 


This section describes the functions used to select the current pen, brush, 
bitmap, or font for a given display context. The selected object is the 
default drawing object used by GDI whenever an output function does not 
specify an explicit drawing object. 


SelectObject ( ADC, hObject ) : hOldObject 


Purpose 
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This function selects the logical object specified by hObject 
as the currently selected object of the specified display con- 
text. The new object replaces the previous object of the 
same type. For example, if hObject is the handle to a logical 
pen, SelectObject replaces the currently selected pen with 
the pen specified by hObject. 


Selected objects are the default objects used by the GDI out- 
put functions to draw lines, fill interiors, write text, and clip 
output to specific areas of the display surface. Although a 
display context can have five selected objects (i.e., pen, 
brush, font, bitmap, and region), no more than one object of 
any given type can be selected at any given time. 
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Parameters hDC isa handle to a display context. 


hObject is a handle to a logical object that has been created 
using one of the following functions: 


Object 
Pen 


Brush 


Font 


Bitmap 


Region 


Function 


Must be created using CreatePen or 
CreatePenIndirect. 


Must be created using CreateSolid- 
Brush, CreateHatchBrush, 
CreatePatternBrush, or 
CreateBrushIndirect. 


Must be created using CreateF ont or 
CreateF ontIndirect. 


Must be created using CreateBitmap, 
CreateBitmapIndirect, or 
CreateCompatibleBitmap. Bitmaps 
can be selected for memory display con- 
texts only, and for only one display con- 
text at a time. 


Must be created using CreateRectRgn, 
CreateEllipticRgn, 
CreatePolygonRgn, CombineRgn, 
CreateRectRgnlindirect, or CreateEl- 
lipticRgnIndirect. 


Heturn Value hOldObdject is a handle to the object being replaced by hOb- 
ygect. It is NULL if there is an error. 


If ADC specifies a metafile, hOldObject is nonzero if the func- 
tion is successful. Otherwise, it is zero. 


SelectClipRgn ( ADC, hRgn): nRgnType 


Purpose This function selects the given region as the current clipping 
region for the specified display context. Only a copy of the 
selected region is used. The region itself can be selected for 
any number of other display contexts or be deleted. 


Parameters hDC isa handle to a display context. 


hfgn is a handle to a region. 
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Return Value nRgnType is a short integer value specifying the region’s 
type. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 


GetObject ( hObject, nCount, lpObject ) : nCopied 


Purpose This function fills a buffer with the logical data that defines 
the logical object specified by hObject. GetObject copies 
nCount bytes of data to the buffer pointed to by lpObzect. 
The function returns data structures of the type LOGPEN, 
LOGBRUSH, LOGFONT, or BITMAP depending on 
the logical object. The buffer must be sufficiently large to 
receive the data. 


Parameters hObject is a handle to a logical pen, brush, font, or bitmap. 


nCount is a short integer value specifying the number of 
bytes to copy to the buffer. 


lp Object is a long pointer to the buffer to receive the infor- 
mation. It must be a data structure of type LOGPEN, 
LOGBRUSH, LOGFONT, or BITMAP, depending on 


the logical object given. 


Return Value nCopted, a short integer value, is the actual number of bytes 
retrieved. It is 0 if there is an error. 


Notes If hObject specifies a bitmap, the function returns only the 
width, height, and color format information of the bitmap. 
The actual bits must be retrieved using the GetBitmap- 
Bits function. 


3.6 Display Context Attribute Functions 


This section describes the functions used to set or examine the current 
attributes of a display context. These attributes include the context’s 
current background color, text color, and mapping mode. 
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Attribute 


Brush 

Pen 

Bitmap 

Font 

Current Pen Position 
Brush Origin 

Relabs Flag 

Text Color 
Background Color 
Background Mode 
Drawing Mode 
Stretching Mode 
Mapping Mode 
Intercharacter Spacing 
Polygon Filling Mode 
Color Table 


Clipping Region 
Window Origin 
Window Extents 
Viewport Origin 
Viewport Extents 
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The default values for the display context attributes are: 


Default Selection 


WHITE_ BRUSH 
BLACK_ PEN 

No default 
SYSTEM_ FONT 
(0,0) 

(0,0) 

ABSOLUTE 
Black 

White 

OPAQUE 

R2_ COPYPEN 
BLACKONWHITE 
MM_ TEXT 

0 

ALTERNATE 


Entries are set to represent an even distribu- 
tion of the full range of available colors. The 
exact default values depend on the device. 
For example, raster devices have black as the 
first entry, white as the last; printers have 
white as the first entry, black as the last. 


The whole display surface 
(0, 0) 
(1, 1) 
(0, 0) 
(1, 1) 
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SetRelAbs ( ADC, nRelAbsMode ) : nOldRelAbsMode 


Purpose 


Parameters 


Return Value 


Notes 


This function sets the relabs flag. This flag specifies 
whether the coordinates in GDI functions are relative to the 
origin of the given device (absolute), or relative to the 
current position (relative). 


hDC is a handle to a display context. 


nelAbsMode is a short integer flag specifying the current 
mode. It can be any one of the following: 


ABSOLUTE Relabs flag set to absolute 
RELATIVE Relabs flag set to relative 


nOldRelAbsMode is a short integer value specifying the pre- 
vious setting of the relabs flag. It can be ABSOLUTE or 
RELATIVE. It is NULL if ADC is not a valid display con- 
text. 


The relabs flag affects the LineTo and PolyLine functions. 


GetRelAbs ( hDC) : nRelAbsMode 


Purpose 


Parameters 


This function retrieves the relabs flag. This flag specifies 
whether the coordinates in GDI functions are relative to the 
origin of the given device (absolute), or relative to the 
current position (relative). 


ADC 'is a handle to a display context. 


Return Value nHelAbsMode is a short integer flag specifying the current 


mode. It can be ABSOLUTE or RELATIVE. It is NULL if 
hDC'is not a valid display context. 


SetBkColor ( ADC, rgbColor ) : rgbOldColor 


Purpose 
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This function sets the current background color to the color 
specified by rgbColor, or to the nearest age color if the 
device cannot represent rgbColor. 


If the background mode is OPAQUE, GDI uses the back- 
ground color to fill the gaps between styled lines, gaps 
between hatched lines in brushes, and character cells. GDI 
also uses the background color when converting bitmaps 
from color to monochrome and vice versa. 


GDI Functions 


The background mode is set by the SetBkMode function. 
See the BitBlt and StretchBlt functions for color bitmap 
conversions. 


Parameters ADC isa handle to a display context. 


rgbColor is an RGB color value specifying the new back- 
ground color. 


Return Value rgbOldColor, is an RGB color value specifying the previous 
background color. If an error occurs, rgbOldColor is 
80000000H. 


GetBkColor ( ADC): rgbColor 


Purpose This function returns the current background color of the 
specified device. 


Parameters hDC isa handle to a display context. 


Return Value rgbColor, an RGB color value, is the current background 
color. 


SetBkMode ( ADC, nBkMode ) : nOldBkMode 


Purpose This function sets the background mode used with text, 
hatched brushes, and line styles. The background mode 
defines whether or not GDI should overwrite existing back- 
ground colors on the display surface before drawing text, 
hatched brushes, or any pen style that is not a solid line. 


Parameters hDC isa handle to a display context. 


nBkMode is a short integer value specifying the background 
mode. It can be one of the following: 


Mode Meaning 
TRANSPARENT Background remains untouched. 
OPAQUE Background is filled with the 


current background color before the 
text, hatched brush, or pen is 
drawn. 


Return Value nOldBkMode is a short integer value specifying the previous 
background mode. It can be TRANSPARENT or OPAQUE. 
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GetBkMode ( ADC) : nBkMode 


Purpose 


Parameters 
Return Value 


This function returns the background mode of the specified 
device. The background mode is used with text, hatched 
brushes, and any pen style that is not a solid line. 


hDC is a handle to a display context. 


nBkMode is a short integer value specifying the current 


background mode. It can be TRANSPARENT or OPAQUE. 


SetTextColor ( ADC, rgbColor ) : rgbOldColor 


Purpose 


Parameters 


Return Value 


This function sets the text color to the color specified by 
rgbColor, or to the nearest logical color if the device cannot 
represent rgbColor. GDI uses the text color to draw the face 
of each character written by the TextOut function. GDI 
also uses the text color when converting bitmaps from color 
to monochrome and vice versa. 


The background color for a character is specified by the 
SetBkColor and SetBkMode functions. See the BitBlt 
and StretchBlt functions for color bitmap conversions. 


hDC'is a handle to a display context. 


rgbColor is an RGB color value specifying the color of the 
text. 


rgbOldColor is an RGB color value specifying the previous 
text color. 


GetTextColor ( hDC): rgbColor 


Purpose 


Parameters 


This function retrieves the current text color. The text 
color defines the foreground color of characters drawn using 
the TextOut function. 


hDC is a handle to a display context. 


Return Value rgbColor, an RGB color value, is the current text color. 


SetROP2 ( ADC, nDrawMode ) : nOldDrawMode 


Purpose 
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This function sets the current drawing mode. GDI uses the 
drawing mode to combine pens and interiors of filled objects 
with the colors already on the display surface. The mode 
specifies how the color of the pen or interior and the color 
——— on the display surface are combined to yield a new 
color. 


Parameters 
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The drawing mode is for raster devices only; it is not avail- 
able on vector devices. See the GetDeviceCaps function 


and the RC_ BITBLT capability. 
hDC'is a handle to a display context. 


nDrawMode is a short integer value specifying the new draw- 
ing mode. It can be any one of the values given in Table 
3.1. 


Return Value nOldDrawMode is a short integer value specifying the previ- 


ous drawing mode. It can be any one of the nDrawMode 
values given in Table 3.1. 


GetROP2 ( hDC): nDrawMode 


Purpose 


Parameters 
Return Value 


Table 3.1 


This function retrieves the current drawing mode. The 
drawing mode specifies how the pen or interior color and the 
color already on the display surface are combined to yield a 
new color. 


hDC is a handle to a display context for a raster device. 


nDrawMode is a short integer value that specifies the draw- 
ing mode. It can be any one of the values given in Table 
3.1. 


Raster Operation Values 


Value 


R2_ BLACK 


Meaning 


Pixel is always black. 


R2_ NOTMERGEPEN Pixel is the inverse of the 


R2_ MERGEPEN color. 


R2_ MASKNOTPEN Pixel is a combination of the colors 


common to both the display and the 
inverse of the pen. 


R2_ NOTCOPYPEN Pixel is the inverse of the pen color. 
R2_ MASKPENNOT Pixel is a combination of the colors 


R2_ NOT 


common to both the pen and the 
inverse of the display. 


Pixel is the inverse of the display color. 
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Table 3.1 (continued) 


Value 
R2_ XORPEN 


R2_ NOTMASKPEN 
R2_ MASKPEN 


R2_ NOTXORPEN 
R2_ NOP 
R2_~ MERGENOTPEN 


R2_ COPYPEN 
R2_ MERGEPENNOT 


R2_ MERGEPEN 


R2_ WHITE 


Meaning 


Pixel is a combination of the colors in the 
pen and in the display, but not in both. 


Pixel is the inverse of R2- MASKPEN color. 


Pixel is a combination of the colors common 
to both the pen and the display. 


Pixel is the inverse of R2_ XORPEN color. 
Pixel remains unchanged. 


Pixel is a combination of the display and 
the inverse of the pen color. 


Pixel is the pen color. 


Pixel is a combination of the pen and the 
inverse of the display color. 


Pixel is a combination of the pen and the 
display color. 


Pixel is always white. 


SetStretchBltMode ( ADC, nStretchMode ) : nOldStretchMode 


Purpose 


This function sets the stretching mode for the StretchBlt 


function. The stretching mode defines which scan lines 
and/or columns StretchBit eliminates when contracting a 


bitmap. 
The nStretchMode can be: 
Mode Meaning 
WHITEONBLACK OR in the “eliminated” lines. 
This mode preserves white pix- 
els at the expense of black pix- 
els by ORing the lines to be 
eliminated with the remaining 
lines. 
BLACKONWHITE AND in the “eliminated” lines. 


This mode preserves black pix- 
els at the expense of white pix- 
els by ANDing the eliminated 
lines with those remaining. 
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Return Value 
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COLORONCOLOR Throw out the “eliminated” 
lines. This mode throws all 
eliminated lines out without 
trying to preserve their infor- 
mation. 


The WHITEONBLACK and BLACKONWHITE modes are 
typically used to preserve foreground pixels in monochrome 
bitmaps. The COLORONCOLOR mode is typically used to 


preserve color in color bitmaps. 
hDC is a handle to a display context. 


nStretchMode is a short integer value specifying the stretch- 
ing mode. 


nOldStretchMode, is a short integer value specifying the pre- 
vious stretching mode. It can be WHITEONBLACK, 
BLACKONWHITE, or COLORONCOLOR. 


GetStretchBltMode ( ADC) : nStretchMode 


Purpose 


Parameters 
Return Value 


This function retrieves the current stretching mode. The 
stretching mode defines how information is to be added or 
removed from bitmaps that are stretched or compressed 
using the StretchBlt function. 


hDC is a handle to a display context. 


nStretchMode is a short integer number specifying the 
current stretching mode. It can be WHITEONBLACK, 
BLACKONWHITE, or COLORONCOLOR. See the 
SetStretchBlt Mode function for an explanation of each 
mode. 


SetPolyFillMode ( hDC, nPolyFillMode ) : nOldPolyFillMode 


Purpose 


This function sets the polygon filling mode for the GDI func- 
tions that use the polygon algorithm to compute interior 
points. The nPolyFillMode can be: 


Mode Meaning 
ALTERNATE Selects alternate mode 
WINDING Selects winding number mode 


In general, the modes differ only in cases where a complex, 
overlapping polygon must be filled (e.g., a five-sided polygon 
that forms a five-pointed star with a pentagon in the 
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Parameters 


center). In such cases, ALTERNATE mode fills every other 
enclosed region within the polygon (i.e., the points of the 
star), but WINDING mode fills all regions (i.e., the points 
and the pentagon). To fill all regions, the WINDING mode 
causes GDI to compute and draw a border that encloses the 
polygon but does not overlap. For example, in the WIND- 
ING mode, the five-sided polygon that forms the star is 
drawn as a ten-sided polygon with no overlapping sides; the 
resulting star is filled. 


hDC is a handle to a display context. 


nPolyFillMode is a short integer value specifying the filling 
mode. 


Return Value nOldPolyFtlMode is a short integer value specifying the pre- 


vious filling mode. It is 0 if there is an error. 


GetPolyFillMode ( ADC): nPolyFillMode 


Purpose 


Parameters 


This function retrieves the current polygon filling mode. 


hDC is a handle to a display context. 


Return Value nPolyltllMode is a short integer value specifying the polygon 


filling mode. It can be one of the following: 
Mode Meaning 


ALTERNATE Alternate mode 
WINDING Winding number mode 


See the SetPolyFillMode function for a description of 
these modes. 


SetMapMode ( hDC, nMapMode ) : nOldMapMode 


Purpose 


Parameters 
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This function sets the mapping mode of the specified display 
context. The mapping mode defines the unit of measure used 
in transforming logical units into device units, and also 
defines the orientation of the device’s x- and y-axes. GDI 
uses the mapping mode to convert logical coordinates into 
the appropriate device coordinates. 


hDC is a handle to a display context. 


GDI Functions 


nMapMode is a short integer value specifying the mapping 
mode. It can be any one of the following: 


Mode 
MM_ TEXT 


MM_ LOMETRIC 


MM_ HIMETRIC 


MM_ LOENGLISH 


MM_ HIENGLISH 


MM_ TWIPS 


Meaning 


Each logical unit is mapped to 
one device pixel. Positive x is 
to the right; positive y is down. 


Each logical unit is mapped to 
one tenth of a millimeter (0.1 
mm). Positive x is to the right; 
positive y is up. 


Each logical unit is mapped to 
one one-hundredth of a millim- 
eter (0.01 mm). Positive x is to 
the right; positive y is up. 


Each logical unit is mapped to 
one one-hundredth of an inch 
(0.01 inches). Positive x is to 
the right; positive y is up. 
Each logical unit is mapped to 
one one-thousandth of an inch 
(0.001 inches). Positive x is to 
the right; positive y is up. 
Each logical unit is mapped to 
one twentieth of a printer’s 
point (1/1440 inches). Positive 
x is to the right; positive y is 
up. 
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MM_ ISOTROPIC Logical units are mapped to 
arbitrary units with equally 
scaled axes; that is, one unit 
along the x-axis is equal to one 
unit along the y-axis. The 
Set WindowExt and Set- 
ViewportExt functions must 
be used to specify the desired 
units and the orientation of the 
axes. GDI makes adjustments 
as necessary to ensure that the 
x and y units remain the same 
size. 


MM_ANISOTROPIC Logical units are mapped to 
arbitrary units with arbitrarily 
scaled axes. The Set Win- 
dowExt and Set Viewport- 
Ext functions must be used to 
specify the desired units, orien- 
tation, and scaling. 


Return Value nOldMapMode is a short integer value specifying the previ- 


Notes 
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ous mapping mode. 


MM_ TEXT mode allows applications to work in device pix- 
els, whose size will vary from device to device. 


The MM_ LOMETRIC, MM_ HIMETRIC, 

MM_ LOENGLISH, MM_ HIENGLISH, and MM_ TWIPS 
modes are useful for applications that need to draw in physi- 
cally meaningful units fowh as inches or millimeters). 


MM_ ISOTROPIC mode ensures a 1:1 aspect ratio, which is 
useful when preserving the exact shape of an image is impor- 
tant. 


MM_— ANISOTROPIC mode allows the x and y coordinates 
to be adjusted independently. 


GDI Functions 


GetMapMode ( hDC') : nMapMode 


Purpose 


Parameters 


This function retrieves the current mapping mode. See Set- 
MapMode for a description of the mapping modes. 


hDC is a handle to a display context. 


Return Value nMapMode is a short integer value specifying the mapping 


mode. 


Set WindowOrg ( ADC, X, Y): ptOldOrigin 


Purpose 


Parameters 


This function sets the window origin of the specified display 
context. The window, along with the display context 
viewport, defines how GDI maps points in the logical coordi- 
nate system to points in the device coordinate system. 


The window origin marks the point in the logical coordinate 
system from which GDI maps the viewport origin, a point in 
the device coordinate system specified by the Set Win- 
dowOrg function. GDI maps all other points by following 
the same process required to map the window origin into the 
viewport origin. For example, all points in a circle around 
the point at the window origin will be in a circle around the 
point at the viewport origin. Similarly, all points in a line 
that passes through the window origin will be in a line that 
passes through the viewport origin. 


hDC is a handle to a display context. 


X and Y are short integer values specifying the x and y coor- 
dinates (in logical units) of the origin of the window. 


Return Value ptOldOrigin is a long integer value specifying the previous 


origin of the window in logical coordinates. The y coordi- 
nate is in the high-order word; the x coordinate is in the 
low-order word. 


Get WindowOrg ( ADC): ptOrigin 


Purpose 


Parameters 


This function retrieves the x and y coordinates of the origin 
of the window associated with the specified display context. 


hDC is a handle to a display context. 


Return Value ptOrtgin is a long integer value containing the origin in logi- 


cal coordinates. The y coordinate is in the high-order word; 
the x coordinate in the low-order word. 
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Set WindowExt ( ADC, X, Y): ptOldExtents 


Purpose 


Parameters 


This function sets the x and y extents of the window associ- 
ated with the specified display context. The window, along 
with the display context viewport, defines how GDI maps 
points in the logical coordinate system to points in the 
device coordinate system. 


The x and y extents of the window define how much GDI 
must stretch or compress units in the logical coordinate sys- 
tem to fit units in the device coordinate system. For exam- 
ple, if the x extent of the window is 2 and the x extent of the 
viewport is 4, GDI maps 2 logical units (measured from the 
x axis) into 4 device units. Similarly, if the y extent of the 
window is 2 and the y extent of the viewport is —1, GDI 
maps 2 logical units (measured from the y axis) into 1 device 
unit. 


The extents also define the relative orientation of the x and 
y axes in both coordinate systems. If the signs of matching 
window and viewport extents are the same, the axes have 
the same orientation. If signs are different, the orientation 
is reversed. For example, if the y extent of the window is 2 
and the y extent of the viewport is —1, GDI maps the posi- 
tive y axis in the logical coordinate system to the negative y 
axis in the device coordinate system. If the x extents are 2 
and 4, GDI maps the positive x axis in the logical coordinate 
system to the positive x axis in the device coordinate sys- 
tem. 


ADC is a handle to a display context. 


A and Y are short integer values specifying the extents of 
the window in logical units. 


Return Value ptOldEztents is a long integer value specifying the previous 
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extents of the window in logical units. The previous y 
extent is in the high-order word; the previous x extent in the 
low-order word. On an error, ptOldEztents is zero. 


Notes 


GDI Functions 


When the following mapping modes are set, calls to 
Set WindowExt and Set ViewportExt are ignored: 


MM_ TEXT 

MM_ LOMETRIC 
MM_ HIMETRIC 
MM_ LOENGLISH 
MM_ HIENGLISH 
MM_ T'WIPS 


When MM_ ISOTROPIC mode is set, GDI makes adjust- 
ments to the window or viewport extents as necessary after 
calls to Set WindowExt or Set ViewportExt to ensure 
that the x and y units remain the same size. 


Get WindowExt ( ADC): ptExtents 


Purpose 


Parameters 


This function retrieves the x and y extents of the window 
associated with the specified display context. 


hDC is a handle to a display context. 


Return Value ptiztents is a long integer value containing the x and y 


extents in logical units. The y extent is in the high-order 
word; the x extent in the low-order word. 


Set ViewportOrg ( hDC, X, Y): ptOldOrigin 


Purpose 


This function sets the viewport origin of the specified 
display context. The viewport, along with the display con- 
text window, defines how GDI maps points in the logical 
coordinate system to points in the coordinate system of the 
actual device. In other words, they define how GDI converts 
logical coordinates to device coordinates. 


The viewport origin marks the point in the device coordi- 
nate system to which GDI maps the window origin, a point 
in the logical coordinate system specified by the Set Win- 
dowOrg function. GDI maps all other points by following 
the same process required to map the window origin into the 
viewport origin. For example, all points in a circle around 
the point at the window origin will be in a circle around the 
point at the viewport origin. Similarly, all points in a line 
that passes through the window origin will be in a line that 
passes through the viewport origin. 
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hDC is a handle to a display context. 


X and Y are short integer values specifying the x and y coor- 
dinates (in device units) of the origin of the viewport. The 
values must be within the range of the device coordinates 
system. 


Return Value ptOldOrigin is a long integer value specifying the previous 


origin of the viewport in device coordinates. The y coordi- 
nate is in the high-order word; the x coordinate is in the 
low-order word. 


Get ViewportOrg (ADC): ptOrigin 


Purpose 


Parameters 


This function retrieves the x and y coordinates of the origin 
of the viewport associated with the specified display context. 


hDC is a handle to a display context. 


Return Value ptOrigin is a long integer value containing the origin in 


device coordinates. The y coordinate is in the high-order 
word; the x coordinate is in the low-order word. 


ScaleWindowExt ( ADC, Xnum, Xdenom, Ynum, Ydenom ): ptOldEztents 


Purpose 


Parameters 


154 


This function modifies the window extents relative to the 
current values. The formulas are: 


xNewWE = (xOldWE * Xnum) / Xdenom 
YNewWE = (yO1ldWE * Ynum) / Ydenom 


The new extent is calculated by multiplying the current 
extents by the given numerator and then dividing by the 
given denominator. 


hDC is a handle to a display context. 


Xnum is a short integer specifying the amount to multiply 
the current x extent. 


Xdenom is a short integer specifying the amount to divide 
the current x extent. 


Ynum is a short integer specifying the amount to multiply 
the current y extent. 


Ydenom is a short integer specifying the amount to divide 
the current y extent. 


GDI Functions 


Return Value ptOldEztents is a long integer value specifying the previous 


window extents in logical units. The previous y extent is in 
the high-order word; the x extent is in the low-order word. 


Scale ViewportExt ( hDC, Xnum, Xdenom, Ynum, Ydenom ) 


Purpose 


Parameters 


ptOldEztents 


This function modifies the viewport extents relative to the 
current values. The formulas are: 


xNewVE 
yNewVE 


(xOldVE * Xnum) / Xdenom 
(yOldVE * Ynum) / Ydenom 


The new extent is calculated by multiplying the current 
extents by the given numerator and dividing by the given 
denominator. 


hDC'is a handle to a display context. 


Xnum is a short integer specifying the amount to multiply 
the current x extent. 


Xdenom is a short integer specifying the amount to divide 
the current x extent. 


Ynum is a short integer specifying the amount to multiply 
the current y extent. 


Ydenom is a short integer specifying the amount to divide 
the current y extent. 


Return Value ptOldExtents is a long integer value specifying the previous 


viewport extents in device units. The previous y extent is in 
the high-order word; the x extent is in the low-order word. 


Offset Window Org ( hDC, X, Y): ptOldOrgs 


Purpose 


Parameters 


This function modifies the viewport origin relative to the 
current values. The formulas are: 


xOldwo + X 
yOldWO + Y 


xNewWO 
yNewWO 


The new origin is the sum of the current origin and the X 
and Y values. 


hDC is a handle to a display context. 


X is a short integer specifying the amount (in logical units) 
to add to the current origin’s x coordinate. 
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Y is a short integer specifying the amount (in logical units) 
to add to the current origin’s y coordinate. 


Return Value ptOldOrgs is a long integer value specifying the previous win- 
dow origin in logical coordinates. The previous y coordinate 
is in the high-order word; the x coordinate is in the low- 
order word. 


Offset ViewportOrg ( hDC, X, Y): ptOldOrgs 


Purpose This function modifies the viewport origin relative to the 
current values. The formulas are: 


xNewVO = xOldVO + X 
yNewVO = yOldvO + Y 


The new origin is the sum of the current origin and the X 
and Y values. 


Parameters hDC isa handle to a display context. 


X is a short integer specifying the amount (in device units) 
to add to the current origin’s x coordinate. 


Y is a short integer specifying the amount (in device units) 
to add to the current origin’s y coordinate. 


Return Value ptOldOrgs is a long integer value specifying the previous 
viewport origin in device coordinates. The previous y coordi- 
nate is in the high-order word; the x coordinate is in the 
low-order word. 


Set ViewportExt ( ADC, X, Y): ptOldExtents 


Purpose This function sets the x and y extents of the viewport of the 
specified display context. The viewport, along with the 
display context window, defines how GDI maps points in the 
logical coordinate system to points in the coordinate system 
of the actual device. In other words, the viewport and 
display context window define how GDI converts logical 
coordinates to device coordinates. 


The x and y extents of the viewport define how much GDI 
must stretch or compress units in the logical coordinate sys- 
tem to fit units in the device coordinate system. For exam- 
ple, if the x extent of the window is 2 and the x extent of the 
viewport is 4, GDI maps two logical units (measured from 
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GDI Functions 


the x axis) into four device units. Similarly, if the y extent 
of the window is 2 and the y extent of the viewport is —1, 
GDI maps 2 logical units (measured from the y axis) into 
one device unit. 


The extents also define the relative orientation of the x and 
y axes in both coordinate systems. If the signs of matching 
window and viewport extents are the same, the axes have 
the same orientation. If signs are different, the orientation 
is reversed. For example, if the y extent of the window is 2 
and the y extent of the viewport is —-1, GDI maps the posi- 
tive y axis in the logical coordinate system to the negative y 
axis in the device coordinate system. If the x extents are 2 
and 4, GDI maps the positive x axis in the logical coordinate 
system to the positive x axis in the device coordinate sys- 
tem. 


hADC'is a handle to a display context. 


AX and Y are short integer values specifying the extents of 
the viewport in device units. 


Return Value ptOldEztents is a long integer value specifying the previous 


Notes 


extents of the viewport in device units. The previous y 
extent is in the high-order word; the previous x extent is in 
the low-order word. On an error, ptOldExtents is zero. 


When the following mapping modes are set, calls to 
Set WindowExt and Set ViewportExt are ignored: 


MM_ TEXT 

MM_ LOMETRIC 
MM_ HIMETRIC 
MM_ LOENGLISH 
MM_ HIENGLISH 
MM_ TWIPS 


When MM_ ISOTROPIC mode is set, GDI makes adjust- 
ments to the window or viewport extents as necessary after 
calls to SetWindowExt or Set ViewportExt to ensure 
that the x and y units remain the same size. 
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Get ViewportExt ( hDC'): ptExtents 


Purpose This function retrieves the x and y extents of the display 
context’s viewport. 


Parameters hDC isa handle to a display context. 


Return Value ptEzxtents is a long integer value containing the x and y 
extents in device units. The y extent is in the high-order 
word; the x extent is in the low-order word. 


GetBrushOrg ( ADC): ptOrigin 


Purpose This function retrieves the current brush origin for the given 
display context. 


Parameter hDC is a handle to a display context. 


Return Value ptOrigin is a long integer value containing the current origin 
of the brush. The x coordinate is in the low-order word and 
the y coordinate is in the high-order word. The coordinates 
are assumed to be in device units. 


Notes The initial brush origin is at 0,0. 
SetBrushOrg ( hDC, X, Y): ptOldOrigin 


Purpose This function sets the origin of all brushes selected into the 
given display context. 


Parameters hDC'isa handle to a display context. 


X and Y are short integers values specifying the origin in 
device coordinates. 


Return Value ptOldOrigin is a long value containing the old origin of the 
brush. The x coordinate is in the low-order word and the y 
coordinate is in the high-order word. 


Notes The initial brush origin is at 0,0. 
SetBrushOrg should not be used with stock objects. 


UnrealizeObject ( ABrush ) : bUnrealized 


Purpose This function directs GDI to reset the origin of the given 
brush the next time it is selected. 


Parameter ABrush is a handle to a logical brush. 
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Return Value 6Unrealized, a Boolean value, is nonzero if the function is 
successful, zero otherwise. 


Notes UnrealizeObject should not be used with stock objects. 


This function must be called whenever a new brush origin is 
set (using SetBrushOrigin). 


The brush specified by ABrush must not be the currently 
selected brush of any display context. 


3.7 Clipping Region Functions 


This section describes the functions used to examine and set the clipping 
region of a display context. The clipping region defines what portion of the 
display surface is clipped. Only images drawn inside the clipping region are 
copied to the surface. The default region is the whole surface. 


GetClipBox ( ADC, lpRect ): nRgnType 


Purpose This function retrieves the dimensions of the tightest bound- 
ing rectangle around the current clipping boundary. The 
dimensions are copied to the buffer pointed to by Ipltect. 


Parameters hDC'is a handle to a display context. 
lpRect is a long pointer to the buffer to receive the rectangle 
dimensions. The buffer must have RECT data structure 
type. 


Return Value nRgnType is a short integer flag specifying the clipping 
region’s type. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 


IntersectClipRect ( ADC, X1, Y1, X2, Y2): nRgnType 


Purpose This function creates a new clipping region by forming the 
intersection of the current region and the rectangle specified 
by X1, Y1, X2, and Y2. GDI clips all subsequent output to 
fit within the new boundary. 
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Parameters 


ADC is a handle to a display context. 


Xi and Yi are short integer values specifying the logical 
coordinates of the upper left corner of the rectangle. 


X2and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the rectangle. 


Return Value nkgnType is a short integer flag specifying the new clipping 


Notes 


region’s type. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 


The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 


OffsetClipRgn ( ADC, X, Y): nRgnType 


Purpose 


Parameters 


This function moves the clipping region of the given device 
by the specified offsets. The function moves the region X 
units along the x-axis and Y units along the y-axis. 


hDC is a handle to a display context. 


X is a short integer value specifying the amount to move left 
or right, in logical units. 


Y is a short integer value specifying the amount to move up 
or down, in logical units. 


Return Value nitgnType is a short integer flag specifying the new region’s 


type. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 


ExcludeClipRect ( hDC, X1, Y1, X2, Y2): nRgnType 


Purpose 


Parameters 
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This function creates a new clipping region that consists of 
the existing clipping region less the specified rectangle. 


hDC is a handle to a display context. 


Xi and Yi are short integer values specifying the logical 
coordinates of the the upper left corner of the rectangle. 


GDI Functions 


A2and Y2 are short integer values specifying the logical 
coordinates of the lower right corner of the rectangle. 


Return Value nftgnType is a short integer flag specifying the new clipping 
region’s type. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 


Notes The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 
PtVisible ( hDC, X, Y): bVistble 


Purpose This function indicates whether or not the given point is 
within the clipping region of the specified display context. 


Parameters hDC isa handle to a display context. 


X and Y are short integer values specifying the logical coor- 
dinates of the point to be checked. 


Return Value 6Vtstble, a Boolean value, is nonzero if the point is within the 
clipping region. Otherwise, it is zero. 
Rect Visible ( ADC, lpRect ) : bVistble 


Purpose This function determines whether or not any part of the 
given rectangle lies within the clipping region of the 
specified display. 


Parameters hDC'is a handle to a display context. 


lpRect is a long pointer to a data structure having RECT 
type. 
Return Value 6Vistble, a Boolean value, is nonzero if some portion of the 


given rectangle lies within the clipping region. Otherwise, it 
is zero. 
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3.8 Region Functions 


This section describes the utility functions used to create and modify 
regions. 


CombineRgn ( hDestRgn, hSrcRgn1, hSrcRgn2, nCombineMode ) 
: niegnType 


Purpose This function creates a new region by combining two exist- 
ing regions. The method used to combine the regions is 
specified by nCombineMode. 


Parameters hDestRgnis a handle to the new region. 
hSrcRgn1 is a handle to one existing region. 
hSrcRgn2 is a handle to the other existing region. 


nCombineMode is a short integer value specifying the opera- 
tion to be performed on the two existing regions. It can be 
any one of the following: 


Value Operation 

RGN_ AND Uses overlapping areas of both 
regions (intersection). 

RGN_ OR Combines all of both regions 
(union). 

RGN_ XOR Combines both regions but removes 
overlapping areas. 

RGNL_ DIFF Saves the areas of Region 1 


hSrcRgn1) that are not part of 
egion 2 (ASrcRgn2). 


RGN_ COPY Creates a copy of Region 1 
(ASrcRgn1). . 


Return Value nRgnType is a short integer flag value indicating the type of 
the resulting region. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 
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EqualRgn ( ASrcRgn1, hSrcRgn2 ) : bEqual 


Purpose 


Parameters 


This function checks the two given regions to determine if 
they are identical. 


hSrcRgn1 is a handle to one region. 


hSrckgn2 is a handle to the other region. 


Return Value bEqual, a Boolean value, is nonzero if the two regions are 


equal. Otherwise, it is zero. 


OffsetRgn ( hRgn, X, Y): nRgnType 


Purpose 


Parameters 


This function moves the given region by the specified offsets. 
The function moves the region X units along the x-axis and 
Y units along the y-axis. 


hRgn is a handle to a region. 


X is a short integer value specifying the amount to move left 
or right. 


Y is a short integer value specifying the amount to move up 
or down. 


Return Value nRgnType is a short integer flag specifying the new region’s 


type. It can be any one of the following: 


ERROR 
NULLREGION 
SIMPLEREGION 
COMPLEXREGION 


CreateRectRgn ( X1, Y1, X2, Y2): hRgn 


Purpose 


Parameters 


This function creates a rectangular region. 


Xi and Yi are short integer values specifying the upper left 
corner of the region. 


X2 and Y2 are short integer values specifying the lower 
right corner of the region. 


Return Value If the function is successful, hRgn is a handle to a new 


Notes 


region. Otherwise, it is NULL. 


The width of the rectangle specified by X1, Y1, X2, and Y2 
must not exceed 32,767 units. 
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CreateRectRgnIndirect ( lpRect ): hRgn 


Purpose 


Parameters 


This function creates a rectangular region. 


lpRect is a long pointer to a data structure having RECT 
type. The structure must contain the coordinates of the 
upper left and lower right corners of the region. 


Return Value If the function is successful, hRgn is a handle to a new 


region. Otherwise, it is NULL. 


CreateEllipticRgn ( X1, Y1, X2, Y2): hRgn 


Purpose 


Parameters 


This function creates an elliptical region. 


Xiand Y1 are short integer values specifying the coordi- 
nates of the upper left corner of the bounding rectangle of 
the ellipse. 


X2and Y2 are short integer values specifying the coordi- 
nates of the lower right corner of the bounding rectangle of 
the ellipse. 


Return Value If the function is successful, hRgn is a handle to a new 


Notes 


region. Otherwise, it is NULL. 


The width and height of the rectangle specified by X1, Y1, 
X2, and Y2 must not exceed 32,767 units. 


CreateEllipticRgnIndirect ( IpRect ): hRgn 


Purpose 


Parameters 


This function creates an elliptical region. 


lpRect is a long pointer to a data structure having RECT 
type. The structure must contain the coordinates of the 
upper left and lower right corners of the bounding rectangle 
of the ellipse. 


Return Value If the function is successful, hRgn is a handle to a new 


region. Otherwise, it is NULL. 


‘ 


CreatePolygonRgn ( [pPoints, nCount, nPolyFillMode ): hRgn 


Purpose 


Parameters 
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This function creates a polygonal region. 


lpPoints is a long pointer to an array of POINT data struc- 
tures. Each point specifies the coordinates of one vertex of 
the polygon. 


nCount is a short integer value specifying the number of 
points in the array. 


GDI Functions 


nPolyFillMode is a short integer value specifying the polygon 
filling mode to be used for filling the region. It can be 
ALTERNATE or WINDING (see the SetPolyFillMode 


function for an explanation of these modes). 


Return Value If the function is successful, hRgn is a handle to a new 


region. Otherwise, it is NULL. 


PtInRegion ( hRgn, X, Y): bSuccess 


Purpose 


Parameters 


This routine specifies whether or not the point given by X 
and Y is in the given region. 


hitgn is a handle to a region. 


X is a short integer value specifying the x coordinate (in log- 
ical coordinates) of the point. 


Yis a short integer value specifying the y coordinate (in log- 
ical coordinates) of the point. 


Return Value bSuccess, a Boolean value, is nonzero if the point is in the 


region. Otherwise, it is zero. 


3.9 Text Justification Functions 


This section describes the functions used to justify text to be written to the 
display surface. The functions are intended to be used with the TextOut 
function which carries out the actual output of text. 


Set TextJustification ( ADC, nBreakExtra, nBreakCount ) : nSet 


Purpose 


This function prepares GDI to justify a line of text using the 
justification parameters specified by nBreakEztra and 
nBreakCount. To justify text, GDI distributes extra pixels 
among break characters in a text line written by the Text- 
Out function. The break character, used to delimit words, 
is usually the space character (ASCII 32), but may be 
defined as some other character by a font. (Get TextMetric 
can be used to retrieve a font’s break character). 


The SetTextJustification function prepares the 
justification by defining the amount of space to be added. 
The nBreakEztra parameter specifies the total amount of 
space (in logical units) to add to the line. The nBreakCount 
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Parameters 


Return Value 


parameter specifies how many break characters are in the 
line. The subsequent TextOut function distributes the 
extra space evenly between each break character in the line. 


The GetTextExtent function is always used with 
SetTextJustification. GetTextExtent computes the 
width before justification of a given line. This width must be 
known before an appropriate nBreakEztra value can be com- 
puted. 


Set TextJustification can be used to justify a line contain- 
ing multiple runs in different fonts. In this case, the line 
must be created piecemeal by justifying and writing each 
run separately. 


Because rounding errors can occur during justification, GDI 
keeps a running error term that defines the current error. 
When justifying a line containing multiple runs, Get Tex- 
tExtent automatically uses this error term when it com- 
putes the extent of the next run, allowing TextOut to 
blend the error into the new run. After each line has been 
justified, this error term must be cleared to prevent it from 
being incorporated into the next line. The term can be 
cleared by calling Set TextJustification with nBreakEztra 
set to zero. 


hDC is a handle to a display context. 


nBreakEztra is a short integer value specifying the total 
extra space (in logical units) to be added to the line of text. 
If the current mapping mode is not MM_ TEXT, nBreakEx- 


tra is transformed and rounded to the nearest pixel. 


nBreakCount is a short integer number specifying the 
number of break characters in the line. 


nSet, a short integer value, is 1 if the function is successful. 
Otherwise, it is 0. 


GetTextExtent ( ADC, IpString, nCount ) : ptTextExtents 


Purpose 
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This function computes the width and height of the line of 
text pointed to by [pString. GetTextExtent uses the 
currently selected font to compute the dimensions of the 
string. The width and height, specified in logical units, are 
computed without considering the current clipping region. 


Parameters 


GDI Functions 


hDC'is a handle to a display context. 
lnString is a long pointer to a text string. 


nCount is a short integer value specifying the number of 
characters in the text string. 


Return Value ptTextExtents, a long integer value, contains the dimensions 


Note 


of the string. The height is in the high-order word; the 
width is in the low-order word. 


Since some devices do not place characters in regular cell 
arrays (e.g. kerning), the sum of the extents of the charac- 
ters in a string may not be equal to the extent of the string. 


Set TextCharacterExtra ( hDC, nCharExtra ) : nOldCharExtra 


Purpose 


Parameters 


This function sets the amount of intercharacter spacing. 
GDI adds this intercharacter spacing to each character, 
including break characters, when it writes a line of text to 
the display surface. 


hDC is a handle to a display context. 


nCharEztra is a short integer value specifying the amount of 
extra space (in logical units) to be added to each character. 
If the current mapping mode is not MM_ TEXT, nCharExztra 
is transformed and rounded to the nearest pixel. 


Return Value nOldCharEztra is a short integer value specifying the previ- 


ous intercharacter spacing. 


GetTextCharacterExtra (ADC): nCharExtra 


Purpose 


Parameters 


This function retrieves the current intercharacter spacing. 
The intercharacter spacing defines the extra space fin logical 
units) that TextOut adds to each character as it writes a 
line. The spacing is used to expand lines of text. 


If the current mapping mode is not MM_ TEXT, Get- 
TextCharExtra transforms and rounds the result to the 
nearest unit. 


hDC is a handle to a display context. 


Return Value nCharEztra is a short integer value specifying the current 


intercharacter spacing. 
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3.10 Metafile Functions 


This section describes the functions used to create, manipulate, and delete 
metafiles. A metafile can be created using the CreateMetaFile function. 
Once created, an application can draw on the file using the functions listed 
below. When drawing is complete, the application must close the metafile 
by using the CloseMetaFile function. This function creates a metafile 
handle that can be used to access and play the metafile. Table 3.2 lists the 
GDI functions which can be used in a metafile. 


Table 3.2 

GDI Functions and Metafiles 

Arc PaintRgn SetMapMode 

Bit Bit PatBlt SetPixel 

Ellipse Pie SetPolyFillMode 
Escape Polygon SetROP2 
ExcludeClipRect Polyline SetRelAbs 

FillRgn Rectangle SetStretchBltMode 
FloodF ill RestoreDC Set TextCharExtra 
FrameRgn RoundRect Set TextColor 
IntersectClipRect SaveDC Set Text Justification 
InvertRgn ScaleViewportExt SetViewportExt 
LineTo ScaleWindowExt SetViewportOrg 
MoveTo SelectClipRgn Set WindowExt 
OffsetClipRect SelectObject Set WindowOrg 
OffsetViewportOrg SetBkColor StretchBit 

Offset WindowOrg SetBkMode TextOut 


SaveDC and RestoreDC calls should be exactly balanced within a 
metafile; that is, there should be as many calls to SaveDC as to 
RestoreDC. Each RestoreDC call must restore a display context that 
was saved within the metafile, that is, relative restore levels should be used 


(for example, “RestoreDC(hDC, -1)”). 
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Bit Blt and StretchBlt copy source bitmaps to the file. The metafile 
display context can be used as both source and destination, but is 
extremely expensive in terms of memory and should be used with caution. 


SelectObject copies the logical object to the file. On playback, GDI 
creates and selects the actual object. At the end of playback, GDI deletes 
the object. 


Escape always passes a NULL value as the long pointer to output data. 


CreateMetaFile ( [pFilename ) : hDC 
Purpose This function creates a metafile display context. 


Parameters  IpFtlename is a long pointer to a null-terminated character 
string specifying the name of the metafile. If lpF'tlename is 
NULL, a display context for a memory metafile is returned. 


Return Value If the function is successful, ADC is a handle to a metafile 
display context. Otherwise, it is NULL. 
CloseMetaFile ( hDC): AMF 


Purpose This function closes the metafile DC and creates a metafile 


handle that can be used to play the metafile using 
Play MetaF le. 


Parameters hDC'is a handle to the metafile display context to be closed. 

Return Value If the function is successful, hMF is a handle to the metafile. 
Otherwise, it is NULL. 

GetMetaFile ( [pFitlename ) : hMF 


Purpose This function creates a handle for the metafile named by 
lpFilename. 


Parameters IpFilename is a long pointer to a null-terminated ASCII 
string specifying the MS-DOS filename of the metafile. The 
metafile is assumed to exist. 


Return Value If the function is successful, AMF is a handle to a metafile. 
Otherwise, it is NULL. 
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CopyMetaFile ( hSrcMetaFile, lpFilename ): hMF 


Purpose 


Parameters 


Return Value 


This function copies the source metafile to the file named by 
lpFtlename and returns a handle to the new metafile. If 
lpF'tlename is NULL, the source is copied to a memory 
metafile. 


hSrcMetafF ile is a handle to a source metafile. 


lpFtlename is a long pointer to a null-terminated character 
string specifying the file to receive the metafile. 


hMF is a handle to the new metafile. 


PlayMetaFile ( hDC, AMF’): bPlayed 


Purpose 


Parameters 


Return Value 


This function plays the contents of the specified metafile on 
the given device context. The metafile can be played any 
number of times. 


hDC is a handle to a display context. 
hMF is a handle to a metafile. 


6bPlayed, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


DeleteMetaFile ( AMF’): bF reed 


Purpose 


Parameters 
Return Value 


This function deletes access to a metafile by freeing the sys- 
tem resources associated with that metafile. It does not 
destroy the metafile itself, but it invalidates the metafile 
handle AMF. The metafile can be used again by getting a 
new handle using the GetMetaF ile function. 


hMF is a handle to a metafile. 


bF reed, a Boolean value, is nonzero if the metafile’s system 
resources are deleted. It is zero if AMF is not a valid handle. 


GetMetaFileBits ( hMF'): hMem 


Purpose 


Parameters 
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This function returns a handle to a global memory block 
containing the specified metafile as a collection of bits. The 
memory block can be used to determine the size of the 
metafile or to save the metafile as a file. The memory block 
should not be modified. 


hMF is a handle to a memory metafile. 


GDI Functions 


Return Value hMem is a handle to the metafile in global memory, if the 


Notes 


function is successful. If an error occurs, hAMemis NULL. 


The handle used as the hMF parameter becomes invalid 
when GetMetaFileBits returns, so hMem must be used to 
refer to the metafile. 


Memory blocks created by this function are unique to the 
calling application and are not shared by other applications. 
These blocks are automatically deleted when the application 
terminates. 


SetMetaFileBits ( hMem ): hMF 


Purpose 


Parameters 


Return Value 


Notes 


This function creates a memory metafile from the data in 
the global memory block specified by hMem. 


hMem is a handle to a global memory block containing 
metafile data. It is assumed that the data was previously 
created using the GetMetaF ileBits function. 


hMF is a handle to a memory metafile if the function is suc- 


cessful. Otherwise, hMF'is NULL. 


After SetMetaFileBits returns, hMF should be used to 
refer to the metafile instead of hMem. 


3.11 Control Functions 


This section describes the functions used to control a display device. 


Escape ( ADC, nEscape, nCount, lpInData, lpOutData ) : nResult 


Purpose 


Parameters 


This function allows applications to access facilities of a par- 
ticular device that are not directly available through GDI. 
Escape calls made by an application are translated and sent 
to the device driver. 


hDC is a handle to a display context. 


niscape is a short integer value specifying the escape func- 
tion to be performed. The following predefined functions 
are available: 


171 


Microsoft Windows Reference Manual 


STARTDOC 

ENDDOC 

NEWFRAME 
NEXTBAND 
SETABORTPROC 
ABORTDOC 
DRAFTMODE 
SETCOLORTABLE 
GETCOLORTABLE 
GETPHYSPAGESIZE 
GETPRINTINGOFFSET 
GETSCALINGFACTOR 
FLUSHOUTPUT 
QUERYESCSUPPORT 


Devices can define additional escape functions. 


nCount is a short integer number specifying the number of 
bytes of data pointed to by [p/nData. 


lpInData is a long pointer to the input data structure 
required for this escape. 


lpOutData is a long pointer to the data structure to receive 
output from this escape. If lpOutData is NULL, no data is 
returned. 


Return Value nResult, a short integer value, is positive if the escape func- 
tion was successful (or is implemented, for the 
QUERYESCSUPPORT escape). nResult is zero if the escape 


is not implemented. A negative value indicates an error. 


The following descriptions give the specific syntax and meaning of each 
Escape call. 


Escape ( ADC, STARTDOC, nCount, lpInData, lpOutData ) : nResult 


Purpose This escape informs the device driver that a new print job is 
starting and that all subsequent NEWFRAME calls should 
be spooled under the same job, until an ENDDOC call 
occurs. This ensures that documents longer than one page 
will not be interspersed with other jobs. 


Parameters nCountis a short integer value specifying the number of 
characters in the string pointed to by lp/nData. 
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lynInData is a long pointer to a null-terminated string speci- 
fying the name of the document. The document name is 
displayed in the spooler window. 


lp OutData is not used and can be set to NULL. 


Return Value nResult, a short integer value, is —1 if an error occurs, such 


Notes 


as insufficient memory or an invalid port specification. Oth- 
erwise, it is positive. 


The correct sequence of events in a printing operation are as 
follows: 


Create printer display context. 


2. Set the abort function to keep out of disk space 
errors from aborting a printing operation. An abort 
procedure that handles these errors must be set 


using the SETABORTPROC escape. 
Begin the printing operation with STARTDOC. 


Begin each new page with NEWFRAME, or each new 
band with NEXTBAND. 


5. End the printing operation with ENDDOC. 


On a printing error, the ENDDOC escape should not be used 
to terminate the printing operation, and the ABORTDOC 
escape should be used to terminate a next banding operation 
only. 


Escape ( hDC, ENDDOC, nCount, lpInData, lpOutData ) : nResult 


Purpose 


Parameters 


Return Value 


Notes 


This escape ends a print job started by a STARTDOC 


escape. 
nCount is not used and can be set to NULL. 
lnInData is not used and can be set to NULL. 
ly OutData is not used and can be set to NULL. 


nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


On a printing error, the ENDDOC escape should not be used 
to terminate the printing operation, and the ABORTDOC 
escape should be used to terminate a next banding operation 
only. 
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Escape ( hDC, NEWFRAME, nCount, lpInData, lpOutData ): nResult 


Purpose 


Parameters 


Return Value 


This escape informs the device that the application has 
finished writing to a page. This escape is typically used 
with a printer to direct the device driver to advance to a 
new page. 


nCount is not used and can be set to NULL. 
lpInData is not used and can be set to NULL. 
lpOutData is not used and can be set to NULL. 


nResult, a short integer value, is positive if the escape is suc- 
cessful. Otherwise, nResult is one of the following: 


Error Code Meaning 
SP_ ERROR General error. 
SP_ APPABORT The job was aborted because 


the application’s abort func- 
tion returned zero. 


SP_ USERABORT The user aborted the job 
through the spooler task. 
SP_ OUTOFDISK Not enough disk space is 


currently available for spool- 
ing, and no more space will 
become available. 


SP_OUTOFMEMORY Not enough memory is avail- 


able for spooling. 


The application can determine whether the error has been 
reported to the user by testing the SP_NOTREPORTED bit 
of the returned error code. If the SP_NOTREPORTED bit 
is set, the error has not been reported. If the bit is zero, the 
user has been notified of the error. 


Escape ( hDC, NEXTBAND, nCount, lpInData, lpOutData ): nResult 


Purpose 
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This escape informs the device driver that the application 
has finished writing to a band, causing the device driver to 
send the band to the spooler and return the coordinates of 
the next band. This escape is used by applications that han- 
dle banding themselves. 


Parameters 
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nCount is not used and can be set to NULL. 
lpInData is not used and can be set to NULL. 


lpOutData is a long pointer to a RECT data structure. The 
device driver copies the device coordinates of the next band 
into this structure. 


Return Value nfesult, a short integer value, is a positive if the escape is 


successful. Otherwise, nResult is one of the following: 


Error Code Meaning 
SP_ ERROR General error. 
SP_ APPABORT The job was aborted because 


the application’s abort func- 
tion returned zero. 


SP_ USERABORT The user aborted the job 
through the spooler task. 
SP_ OUTOFDISK Not enough disk space is 


currently available for spool- 
ing, and no more space will 
become available. 


SP_OUTOFMEMORY Not enough memory is avail- 


able for spooling. 


The application can determine whether the error has been 
reported to the user by testing the SP_NOTREPORTED bit 
of the returned error code. If the SP_NOTREPORTED bit 
is set, the error has not been reported. If the bit is zero, the 
user has been notified of the error. 


Escape ( ADC, SETABORTPROC, nCount, lpInData, lpOutData ) : nResult 


Purpose 


This escape sets the abort function for the print job. If an 
application wants to allow the print: job to be cancelled dur- 
ing spooling, it must set the abort function before the print 
Job is started with the STARTDOC escape. The spooler 
calls the abort function during spooling to allow the applica- 
tion to cancel the print job or to handle out-of-disk-space 
conditions. If no abort function is set, the print job will fail 
if there is not enough disk space for spooling. 
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Parameters nCountis not used and can be set to NULL. 
lpInData is a long pointer to the abort function. 
lp OutData is not used and can be set to NULL. 


Return Value nfesult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Notes The abort function has the following form: 
AbortFunc (hPr, code) : bContinue 


hPr is a handle to the printer display context. 


code, a short integer value, is 0 if no error has occurred. It 
is SP_OUTOFDISK if the spooler is currently out of disk 
space, but more will become available if the application is 
willing to wait. 


bContinue, a Boolean value, should be nonzero if the print 
job is to be continued, and zero if it is cancelled. 


Escape ( hDC, ABORTDOC, nCount, lpInData, lpOutData ) : nResult 


Purpose This escape aborts the current job, erasing everything the 
application has written to the device since the last END- 
DOC escape. 


The ABORTDOC escape should be used for printing opera- 
tions that do not specify an abort function (SETABORT- 
PROC escape), and to terminate printing operations that 
have not yet reached their firs; NEWFRAME or 
NEXTBAND call. 


Parameters nCountis not used and can be set to NULL. 
lpInData is not used and can be set to NULL. 
lpOutData is not used and can be set to NULL. 


Return Value nfesult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Notes On a printing error, the ENDDOC escape should not be used 
to terminate the printing operation, and the ABORTDOC 
escape should be used to terminate a next banding operation 
only. 
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Escape ( ADC, DRAFTMODE, nCount, lpInData, lpOutData ) : nResult 


Purpose 


Parameters 


Return Value 


Notes 


This escape turns draft mode off or on. Turning draft mode 
on instructs the device driver to print faster and with lower 
quality (if eres The draft mode can only be changed 
at page boundaries (for example, after a NEWFRAME 
escape.) 


nCount is a short integer value specifying the number of 
bytes pointed to by lp/nData. 


lpInData is a long pointer to a short integer value specifying 
the draft mode: 1 for draft mode on, 0 for off. 


lp OutData is not used and can be set to NULL. 


nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


The default draft mode is off. 


Escape ( ADC, SETCOLORTABLE, nCount, lpInData, lpOutData ) 


Purpose 


Parameters 


Return Value 


Notes 


: nResult 


This escape sets an RGB color table entry. If the device can- 
not supply the exact color, the function sets the entry to the 
closest possible approximation of the color. 


nCount is not used and can be set to NULL. 


lpInData is a long pointer to a data structure having the fol- 
lowing items: 


WORD Index; 
LONG rgb; 


The /ndez is the color table index. Color table entries start 
at O for the first entry. The rgb is the desired RGB color 
value. 


lp OutData is a long pointer to an RGB color value. The 
device driver copies the new color value to this location. 


nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


A device’s color table is a shared resource; changing the sys- 
tem display color for one window changes it for all windows. 


The SETCOLORTABLE escape has no effect on devices with 
fixed color tables. 
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Escape ( hDC, GETCOLORTABLE, nCount, lpInData, lpOutData ) 


Purpose 


Parameters 


Return Value 


: nResult 


This escape retrieves an RGB color color table entry and 
copies it to the location specified by lpOutData. 


nCount is not used and can be set to NULL. 


lpInData is a long pointer to a short integer value specifying 
the index of a color table entry. Color table indexes start at 
0 for the first table entry. 


lpOutData is a long pointer to an RGB color value. 


nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Escape ( hDC, GETPHYSPAGESIZE, nCount, lpInData, lpOutData ) 


Purpose 


Parameters 


Return Value 


: nResult 


This escape retrieves the physical page size and copies it to 
the location pointed to by /[pOutData. 


nCount is not used and can be set to NULL. 
lpInData is not used and can be set to NULL. 


lp OutData is a long pointer to a POINT structure. The 
device driver fills this structure with the physical page 
dimensions in device units. The horizontal size is in the x 
coordinate; the vertical size is in the y coordinate. 


nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Escape ( hDC, GETPRINTINGOFFSET, nCount, lpInData, lpOutData ) 


Purpose 


Parameters 


178 


: nResult 


This escape retrieves the offset, from the upper left hand 
corner of the physical page, where the actual printing or 
drawing begins. This escape function is not generally useful 
for devices that allow the user to set the printable origin by 


hand. 
nCount is not used and can be set to NULL. 
lpInData is not used and can be set to NULL. 


lp OutData is a long pointer to a POINT structure. The 
device driver fills this structure with the offset in device 
units. 
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Return Value nfesult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Escape ( hDC, GETSCALINGFACTOR, nCount, lpInData, lpOutData ) 
: nResult 


Purpose This escape retrieves the scaling factors for the x and y axes 
of a printing device. For each scaling factor, the escape 
copies an exponent of two to the location pointed to by 
lpOutData. For example, the value 3 is copied to lpOutData 
if a scaling factor is 8. 


Scaling factors are used by printing devices that cannot sup- 
port graphics at the same resolution as the device resolu- 
tion. 


Parameters nCount is not used and can be set to NULL. 
lpInData is not used and can be set to NULL. 


lpOutData is a long pointer to a POINT structure. The 
device driver copies the scaling factors for the x and y axes 
to the structure. 


Return Value nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Escape ( ADC, FLUSHOUTPUT, nCount, lpInData, lpOutData ): nResult 
Purpose This escape flushes output in the device’s buffer. 
Parameters nCountis not used and can be set to NULL. 

lpInData is not used and can be set to NULL. 

lp OutData is not used and can be set to NULL. 


Return Value nResult, a short integer value, is positive if the function is 
successful. Otherwise, it is negative. 


Escape ( hDC, QUERYESCSUPPORT, nCount, lpInData, lpOutData ) 


: nResult 


Purpose This escape finds out whether a particular escape function is 
implemented by the device driver. The return value is 
nonzero for implemented escape functions, and zero for 
unimplemented escape functions. 


Parameters nCountis a short integer value specifying the number of 
bytes pointed to by lp/nData. 
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lpnInData is a long pointer to a short integer value specifying 
the escape function to be checked. 


lp OutData is not used and can be set to NULL. 


Return Value nResult, a short integer value, is nonzero for implemented 
escape functions. Otherwise, it is zero. 


3.12 GDI Information Functions 


This section describes the functions used to retrieve information about GDI 
and specific devices. 


EnumFonts ( ADC, IpFacename, lpFontFunc, lpData ) : nResult 


Purpose This function enumerates the fonts available on a given 
device. For each font having the facename specified by 
lpFacename, EnumFonts retrieves information about that 
font and passes it to the function pointed to by [pFontF unc. 
The callback function, an application-supplied function, can 
process the font information as desired. Enumeration con- 
tinues until there are no more fonts or the callback function 
returns zero. 


Parameters hDC isa handle to a display context. 


lpFacename is a long pointer to a null-terminated ASCII 
string specifying the facename of the desired fonts. If 
lpFacename is NULL, EnumFonts randomly selects and 
enumerates one font of each face available. 


lpFontF unc is a long pointer to the application-supplied call- 
back function. 


lpData is a long pointer to the application-supplied data. 
The data is passed to the callback function along with the 
font information. 


Return Value nfesult, a short integer value, is equal to the last value 
returned by the callback function. Its meaning is user- 


defined. 
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The callback function must have the form: 


lpFontFunc(lpLogFont, lpTextMetrics, Font Type, lpData):nResult 


where [pLogFont is a long pointer to a data structure having 
LOGFONT type, [p TextMetrics is a long pointer to a data 
structure having TEXTMETRIC type, FontType is a 
short integer value specifying the type of the font, and 
lpData is a long pointer to the application-supplied data 
passed to EnumF onts. 


The return value, nResult, can be any integer value. 


The AND operator (&) can be used with the 

RASTER_ FONTTYPE and DEVICE_ FONTTYPE con- 
stants to determine the font type. The 

RASTER_ FONTTYPE bit of FontType specifies whether or 
not the font is a raster or vector font. If the bit is 1, the 
font is a raster font; if 0, a vector font. The 

DEVICE_ FONTTYPE bit of FontType specifies whether or 
not the font is a device- or GDI-based font. If the bit is 1, 
the font is a device-based font; if 0, a GDI-based font. 


If the device is capable of text transformations (scaling, ital- 
icizing, etc.) only the base font will be enumerated. The user 
is responsible for inquiring the device’s text transformation 
abilities to determine which additional fonts are available 
directly from the device. GDI can simulate the emboldened, 
italic, underlined, and strikeout attributes for any font. 


EnumFonts only enumerates fonts from the GDI internal 
table. This does not include fonts that are generated by a 
device, such as fonts that are transformations of fonts from 
the internal table. GetDeviceCaps can be used to deter- 
mine what type of transformations a device can perform. 
This information is available using the TEXTCAPS index. 


GDI can scale GDI-based raster fonts by 1 to 5 horizontally 
and 1 to 8 vertically, unless PROOF_ QUALITY is being 


used. 


EnumObjects ( hDC, nObjectType, lpObjectF'unc, lpData ) : nResult 


Purpose 


This function enumerates the pens and brushes available on 
a device. For each object belonging to the given style, the 
callback function is called with the information for that 
object. The callback function is called until there are no 
more objects or the callback function returns zero. 
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Parameters 


hDC is a handle to a display context. 


nObject Type is a short integer value identifying the object 
type. It can be one of the following: 


OBJ_ PEN 
OBJ_ BRUSH 


lpObjectF'unc is a long pointer to the application-supplied 
callback function. 


lpData is a long pointer to the application-supplied data. 
The data is passed to the callback function along with the 
object information. 


Return Value nfesult, a short integer value, is equal to the last value 


Notes 


returned by the callback function. Its meaning is user- 


defined. 

The callback function must have the form: 

functionname (lpObj, lpData) 

where [pObj is a pointer to a logical pen or brush and [pData 


is a long pointer to the application-supplied data passed to 
EnumObjects. 


GetTextFace ( ADC, nCount, lpFacename ): nCopied 


Purpose 


Parameters 


This function copies the facename of the currently selected 
font into a buffer pointed to by IpFacename. The facename 
is copied as a null-terminated ASCII string. The nCount 
parameter specifies the maximum number of characters to 
copy. If the name is longer than nCount, is it truncated. 


hDC is a handle to a display context. 


nCount is a short integer value specifying the size of the 
buffer in bytes. 


lpFacename is a long pointer to the buffer to receive the 
facename. 


Return Value nCopted, a short integer value, is the actual number of bytes 
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copied to the buffer. It is 0 if there is an error. 
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Get TextMetrics ( ADC, lpMetrics ): bRetrieved 


Purpose 


Parameters 


Return Value 


This function fills the buffer pointed to by lpMetrics with the 
metrics for the currently selected font. 


hDC'is a handle to a display context. 


lpMetrics is a long pointer to a data structure having 


TEXTMETRIC type. 


bRetrieved, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


GetDeviceCaps ( ADC, nIndez ): nValue 


Purpose 


Parameters 


Return Value 


Table 3.3 


This function retrieves device-specific information about a 
given display device. The n/ndex parameter specifies the 
type of information desired. 


hDC is a handle to a display context. 


nindex is a short integer value specifying the item to return. 
It can be any one of the values given in Table 3.3. 


nValue is the integer value of the desired item. 


GDI Information Indexes 


Index 


Meaning 


DRIVERVERSION The version number. (100H) 


TECHNOLOGY 


HORZSIZE 
VERTSIZE 
HORZRES 


The device technology. It can be any one of the 
following: 


0 Vector plotter 

Raster display 

Raster printer 

Raster camera 

Character-stream, PLP 

Metafile, VDM 

Display-file 

The width of the physical display in millimeters. 
The height of the physical display in millimeters. 


The width of the display in pixels. 


oof Oh 
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Table 3.3 (continued) 


Index 


VERTRES 
BITSPIXEL 
PLANES 
NUMBRUSHES 
NUMPENS 
NUMFONTS 
NUMCOLORS 
ASPECTX 


ASPECTY 


ASPECTXY 


PDEVICESIZE 
CLIPCAPS 


RASTERCAPS 


CURVECAPS 
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Meaning 


The height of the display in raster lines. 

The number of adjacent color bits for each pixel. 
The number of color planes. 

The number of device-specific brushes. 

The number of device-specific pens. 

The number of device-specific fonts. 

The number of entries in the device’s color table. 


The relative width of a device pixel as used for line 
drawing. 


The relative height of a device pixel as used for line 
drawing. 


The diagonal width of the device pixel as used for line 
drawing. 


The size of the internal data structure PDE VICE. 


A flag indicating the clipping capabilities of the device. 
It is 1 if the device can clip to a rectangle. It is 0 if it 
cannot clip. 


A flag indicating the raster capabilities of the device, as 
follows: 

RC_ BITBLT - Capable of transferring bitmaps. 

RC_ BANDING - Requires banding support. 

RC_ SCALING - Capable of scaling. 


A bitmask indicating the curve capabilities of the 
device. The bits have the following meanings: 

bit O - set means can do circles 

bit 1 - set means can do pie wedges 

bit 2 - set means can do chord arcs 

bit 3 - set means can do ellipses 

bit 4 - set means can do wide borders 

bit 5 - set means can do styled borders 

bit 6 - set means can do borders that are wide and 
styled 

bit 7 - set means can do interiors 

The high-order byte is 0. 
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Table 3.3 (continued) 


Index 


LINECAPS 


POLYGONALCAPS 


TEXTCAPS 


Note 


Meaning 


A bitmask indicating the line capabilities of the device. 
The bits have the following meanings: 

bit 0 - reserved 

bit 1 - set means can do polyline 

bit 2 - reserved 

bit 3 - reserved 

bit 4 - set means can do wide lines 

bit 5 - set means can do styled lines 

bit 6 - set means can do lines that are wide and styled 
bit 7 - set means can do interiors 

The high-order byte is 0. 


A bitmask indicating the polygonal capabilities of the 
device. The bits have the following meanings: 

bit 0 - set means can do alternate fill polygon 

bit 1 - set means can do rectangle 

bit 2 - set means can do winding number fill polygon 
bit 3 - set means can do scanline 

bit 4 - set means can do wide borders 

bit 5 - set means can do styled borders 

bit 6 - set means can do borders that are wide and 
styled 

bit 7 - set means can do interiors 

The high-order byte is 0. 


A bitmask indicating the text capabilities of the device. 
The bits have the following meanings: 

bit O- set means can do character output precision 

bit 1- set means can do stroke output precision 

bit 2 - set means can do stroke clip precision 

bit 3- set means can do 90 degree character rotation 
bit 4- set means can do any character rotation 

bit 5- set means can do scaling independent of X and Y 
bit 6 - set means can do doubled character for scaling 
bit 7 - set means can do integer multiples for scaling 
bit 8 - set means can do any multiples for exact scaling 
bit 9 - set means can do double weight characters 

bit 10 - set means can do italicizing 

bit 11 - set means can do underlining 

bit 12 - set means can do strikeouts 

bit 13 - set means can do raster fonts 

bit 14 - set means can do vector fonts 

bit 15 - Reserved. Must be returned zero. 


All of the available abilities are described under the 
LOGFONT data structure. 
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SetEnvironment ( [pPortName, lpEnviron, nCount ) : nCopted 


Purpose 


Parameters 


Return Value 


Notes 


This function copies the contents of the buffer specified by 
lpEnvtron into the environment associated with the device 
attached to the system port specified by IpPortName. 
SetEnvironment overwrites any existing environment. If 
there is no environment for the given port, SetEnviron- 
ment creates it. If nCount is 0, the existing environment is 
deleted and not replaced. 


lpPortName is a long pointer to a null-terminated string 
specifying the name of the desired port. 


lpEnvtron is a long pointer to the buffer containing the new 
environment. 


nCount is a short integer value specifying the number of 
bytes to be copied. 


nCopted is a short integer value specifying the number of 
bytes copied to the environment. It is 0 if there is an error. 
It is —1 if the environment is deleted. 


The first field in the buffer pointed to by lpEnviron must be 
the same as passed in the [pDeviceName parameter of the 

CreateDC function. If lpPortName specifies a null port (as 
defined in the WIN.INI file), the device name pointed to by 


lnEnvtron is used to locate the desired environment. 


GetEnvironment ( [pPortName, lpEnviron, nMazxCount ) : nCopied 


Purpose 


Parameters 
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This function copies the current environment associated 
with the device attached to the system port specified by 
lpPortName into the buffer specified by IpEnviron. The 
environment, maintained by GDI, contains binary data used 
by GDI whenever a display context (DC) is created for the 
device on the given port. 


The function fails if there is no environment for the given 
port. | 


lpPortName is a long pointer to a null-terminated string 
specifying the name of the desired port. 


lnEnvtron is a long pointer to the buffer that will receive the 
environment. 


nMazxCount is a short integer value specifying the maximum 
number of bytes to copy. 
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Return Value nCopted is a short integer value specifying the number of 


Notes 


bytes copied to /pData. It is 0 if the environment cannot be 
found. 


The first field in the buffer pointed to by [pEnviron must be 
the same as passed in [pDeviceName parameter of the 
CreateDC function. If lpPortName specifies a null port (as 
defined in in the WIN.INI file), the device name pointed by 
lnEnviron is used to locate the desired environment. 


GetDCOrg ( ADC): ptOrigin 


Purpose 


Parameters 


This function returns the final translation origin for the 
screen display context. The final translation origin specifies 
the offset used by Windows to translate device coordinates 
into client coordinates for points in an application’s win- 
dow. The final translation origin is relative to the physical 
origin of the screen display. 


ADC is a handle to a display context. 


Return Value ptOrigin is long integer value containing the final translation 


Notes 


origin in device coordinates. The y coordinate is in the 
high-order word; the x coordinate in the low-order word. 


The final translation origin is nonzero for screen display con- 
texts only. 


GetNearestColor ( hDC, rgbColor ) : rgbSolidColor 


Purpose 


Parameters 


Return Value 


This function takes a logical color and returns the closest 
logical color the device can represent. 


hDC is a handle to a device display context. 


rgbColor is an RGB color value specifying the color to be 
matched. 


rgbSoltdColor, an RGB color value, is the solid color closest 
to rgbColor that the device can represent. 


3.13 Conversion Functions 


This section describes the functions used to convert logical coordinates into 
device coordinates, and vice versa. Logical coordinates specify points in 

GDP’s logical coordinate system and are device-independent. Device coordi- 
nates specify points on a device’s display surface and are device-dependent. 
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DPtoLP ( ADC, lpPotints, nCount ) : bConverted 


Purpose 


Parameters 


Return Value 


This function converts device points into logical points. ‘The 
function maps the coordinates of each point specified by 
lpPoints from the device coordinate system into GDI’s logi- 
cal coordinate system. The conversion depends on the 
current mapping mode and the settings of the origins and 
extents for the device’s window and viewport. 


hDC is a handle to a display context. 


lynPotnts is a long pointer to an array of points. Each point 
must be a data structure having POINT type. 


nCount is a short integer value specifying the number of 
points pointed to by [pPornts. 


bConverted, a Boolean value, is nonzero if all points are con- 
verted. Otherwise, it is zero. 


LPtoDP ( ADC, lpPoints, nCount ) : bConverted 


Purpose 


Parameters 


Return Value 
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This function converts logical points into device points. The 
function maps the coordinates of each point specified by 
lpPotnts from GDI’s logical coordinate system into a device 
coordinate system. The conversion depends on the current 
mapping mode. 


hDC is a handle to a display context. 


lpPotnts is a long pointer to an array of points. Each point 
must be a data structure having POINT type. 


nCount is a short integer value specifying the number of 
points pointed to by lpPotnts. 


bConverted, a Boolean value, is nonzero if all points are con- 
verted. Otherwise, it is zero. 
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4.1 Introduction 


This chapter describes the system resource functions. These functions pro- 
vide access to the resources of the Windows system, such as memory and 
file resources. 


4.2 Module Manager Functions 


This section describes the functions used to access the code and data in 
Windows executable modules. 


GetModuleHandle ( [pModuleName ) : hModule 


Purpose This function retrieves the module handle of the specified 
module. 


Parameter lpModuleName is a long pointer to a null-terminated ASCII 
string specifying the module name. 


Return Value hModule is a handle to the module if the function is success- 
ful. Otherwise, it is NULL. 

GetModule Usage ( hModule ) : nCount 

Purpose This function returns the reference count of a given module. 

Parameters hModule is a module handle or an instance handle. 


Return Value nCount is a short integer value specifying the reference 
count of the module. 


GetModuleFileName ( hModule, IpFilename, nSize ): nLength 


Purpose This function retrieves the name of the executable file from 
which the specified module was loaded. The function copies 
the null-terminated name into the buffer pointed to by 
lpFilename. 


Parameters hModule is a module handle or an instance handle. 


lpF'tlename is a long pointer to the buffer where the filename 
will be stored. 


nSize is a short integer specifying the size of the buffer. If 
the filename is longer than nSize, it is truncated. 
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Return Value nLength is a short integer specifying the actual length of the 


string stored in the buffer. 


GetInstanceData ( Alnstance, pData, nCount ) : nBytes 


Purpose 


Parameters 


This function copies data from a previous instance of an 
application into the data area of the current instance. The 
hinstance parameter specifies which instance to copy data 
from. The pData parameter specifies where to copy the 
data, and nCount specifies the number of bytes to copy. 


hInstance is the instance handle of a previous invocation of 
the application. 


pData is a short pointer to a buffer in the current instance. 


nCount is a short integer number specifying the number of 
bytes to copy. 


Return Value nBytes, a short integer value, is the number of bytes actually 


copied. 


GetProcAddress ( hModule, lpProcName ) : lpAddress 


Purpose 


Parameters 
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This function retrieves the memory address of the function 
whose name is pointed to by [lpProcName. GetProcAd- 
dress searches for the function in the module specified by 
hModule, or in the current module if hModule is NULL. The 
function must be an exported function; the module’s 
definition file must contain an appropriate EXPORTS line 
for the function. 


The retrieved address points to prolog code that is executed 
before the function is executed. The prolog code loads the 
data segment of the specified module instance. Thus, when 
the function is invoked using the retrieved address, the 
correct data segment will be loaded before the function is 
executed. 


hModule is a module handle or an instance handle of the 
module containing the function. If hModule is a module han- 
dle, the most recent instance of the module is used. 


lpFuncttonName is a long pointer to a character string nam- 
ing the function. The string must be a null-terminated 


ASCII string. 
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Return Value lpAddress is a long pointer to the function’s entry point if 


Note 


the function is successful. Otherwise, it is NULL. 


GetProcAddress should be used to retrieve addresses of 
exported functions belonging to other modules only. The 
MakeProclInstance function can be used to access func- 
tions within different instances of the current module. 


GetCodeHandle ( [pProc ) : hCode 


Purpose 


Parameters 


This function returns the handle of the code segment con- 
taining the function pointed to by IpProc. 


lpProc is a long pointer to a function. 


Return Value hCode is the handle of the code segment containing the func- 


Notes 


tion. 


If the code segment containing the function is already 
loaded, GetCodeHandle marks the segment as recently 
used. If the code segment is not loaded, GetCodeHandle 
attempts to load it. Thus, an application can use this func- 
tion to attempt to preload one or more segments needed to 
perform a particular task. 


MakeProclInstance ( IpProc, hInstance ) : lpAddress 


Purpose 


Parameters 


This function binds the data segment of the module instance 
specified by hinstance to the function pointed to by [pProc. 


The address returned by MakeProcInstance points to pro- 
log code that is executed before the function is executed. 
The prolog code loads the data segment of the specified 
module instance. Thus, when the function is invoked using 
the retrieved address, the correct data segment will be 
loaded before the function is executed. 


lpProc is the long pointer, before binding, to the desired 
function. 


hInstance is the instance handle associated with the desired 
data segment. 


Return Value lpAddress is the long pointer, after binding, to the function 


if the function is successful. Otherwise, it is NULL. 
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Notes 


MakeProclnstance should be used to access functions 
from instances of the current module only. The function is 
not required if the module has a single data segment for all 
instances. GetProcAddress should be used to access func- 
tions exported by other modules. 


After MakeProclInstance has been called for a particular 
function, all calls to the function should be made through 
the retrieved address. 


FreeProcInstance ( [pProc ) 


Purpose 


Parameters 


This function frees the function specified by lpProc from the 
data segment bound to it by the MakeProcInstance func- 
tion. When the function is subsequently invoked, it uses its 
default data segment. 


lpProc is a long pointer to a function. The address must 
have been previously created using the MakeProcInstance 
function. 


Return Value None. 


LoadLibrary ( [pLibFileName ) : hLibModule 


Purpose 


Parameter 


This function loads the library module contained in the 
specified file and returns a handle to the loaded module. 


lpLibF'tleName is a long pointer to a string specifying the 
name of the library file. The string must be a null- 
terminated ASCII string. 


Return Value hLibModule is a handle to the loaded library module. It is 


NULL if the given file is not a library file. If the return 
value is less than 32, the value represents an MS-DOS sys- 
tem call error code (2, 8, or 11). 


FreeLibrary ( hLibModule ) 


Purpose 


Parameter 


This function decreases the reference count of the loaded 
library module by one. When the reference count reaches 
zero, the memory occupied by the module is freed. 


hLibModule is a handle to a loaded library module. 


Return Value None. 
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Get Version ( ): wVerston 


Purpose 
Parameters 
Return Value 


This function returns the current version of Windows. 
None. 


wVerston is an unsigned short integer value specifying the 

major and minor version number of Windows. The high- 

order byte is the minor version (revision) number; the low- 
order byte is the major version number. 


Catch ( [pCatchBuf ) : nThrowBack 


Purpose 


Parameters 


Return Value 


This function catches the current execution environment 
and copies it the the buffer pointed to by IpCatchBuf. The 
buffer can then be used by the Throw function to restore 
the execution environment to the saved values. The execu- 
tion environment includes the state of all system registers 
and instruction counter. 


lnCatchBuf is a long pointer to a buffer having CATCHBUF 
type. 


nThrowBack, a short integer value, is zero if the environment 
is copied to the buffer. 


Throw ( [pCatchBuf, nThrowBack ) 


Purpose 


Parameters 


This function restores the execution environment to the 
values saved in the buffer pointed to by [pCatchBuf. Execu- 
tion then continues at the Catch function that copied the 
environment to [pCatchBuf. The nThrowBack parameter is 
passed as the return value to the Catch function. It can be 
any nonzero integer value. 


lp CatchBuf is a long pointer to a buffer having CATCHBUF 
type. 


nThrowBack is a short integer to be returned to the Catch 
function. | 


Return Value None. 
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4.3 Memory Manager Functions 


This section describes the functions used to allocate and manage global and 
local memory. Windows provides two heaps for memory allocation during 
program execution: the global heap and the application’s local heap. 


The global heap is all of system memory that is not explicitly allocated for 
Windows or applications. Any application can allocate one or more blocks 
of memory from the global heap. Global memory blocks can be any size. 


The local heap is free memory in the application’s data segment. The user 
specifies the size of this heap in the application’s module definition file. 
The application can allocate one or more blocks of local heap, but no block 
may be larger than available memory. The maximum size for any local 
heap is 64K bytes. 


The application is responsible for freeing any memory it has allocated. 


GlobalAlloc ( wF lags, dwBytes ) : hMem 


Purpose This function allocates dwBytes of memory from the global 
heap. The memory can be fixed or moveable, depending on 
the memory type specified by Flags. 


Parameters _wF lags is an unsigned short integer flag value specifying how 
to allocate the memory. It can be any one of the following: 


Value Meaning 

GMEM_ FIXED Memory is fixed (the 
default). 

GMEM_ MOVEABLE Memory is moveable. 

GMEM_ ZEROINIT Memory contents are initial- 


ized to zero. 
GMEM_DISCARDABLE Memory is discardable. 
GMEM_ NODISCARD Discarding of objects will 


not be performed in order to 
satisfy the allocation 
request. 


GMEM_ NOCOMPACT Memory compaction and dis- 
carding will not be per- 
formed in order to satisfy 
the allocation request. 
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dwBytes is an unsigned long integer value specifying the 
number of bytes to allocate. 


Return Value hMemis a global memory handle if the function is successful. 


Otherwise, it is NULL. 


GlobalCompact ( dwMinFree ): dwLargest 


Purpose This function generates dwMinF ree free bytes of global 
memory by compacting, if necessary, the system’s global 
heap. The function checks global heap for dwMtnF ree con- 
tiguous free bytes. If the bytes do not exist, GlobalCom- 
pact compacts memory by first moving all unlocked move- 
able blocks into high memory. If this does not generate the 
requested amount of space, the function discards unlocked 
discardable moveable blocks until the requested space is 
available. 


Parameters dwMitnFree is an unsigned long integer specifying the 
number of free bytes desired. If dwMtnF ree is zero, the func- 
tion returns a value but does not compact memory. 


Return Value dwlLargest is an unsigned long integer specifying the number 
of bytes in the largest block of free global memory. 
GlobalDiscard ( hMem ) : hOldMem 


Purpose This function discards the global memory block specified by 
hMem. 


Parameters hMemisa handle to a global memory block. 

Return Value hOldMemis NULL if the function is successful. Otherwise, it 
is equal to hMem. 

GlobalF ree ( hMem ): hOldMem 


Purpose This function frees the global memory block identified by 
hMem. 


Parameters hMemis a handle to the global memory block to be freed. 


Return Value hOldMem is NULL if the function is successful. Otherwise, 
it is equal to hMem. 


Notes GlobalF ree must not be used to free a locked memory 
block. The block must first be unlocked using the 
GlobalUnlock function. 
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GlobalLock ( hMem ): lpAddress 


Purpose 


Parameters 


This function retrieves the absolute memory address of the 
global memory block specified by hMem. The block is 
locked into memory at the given address and its reference 
count is incremented by one. Locked memory is not subject 
to moving or discarding. 


The block remains locked in memory until its reference 
count is decremented to zero using the GlobalUnlock func- 
tion. 


hMem is a handle to the global memory block to be locked. 


Return Value IlpAddress is a long pointer to the first byte of memory in the 


Notes 


global block if the function is successful. If the object has 
been discarded or there is an error, [pAddress is NULL. 


Discarded objects always have a reference count of zero. 


GlobalReAlloc ( hMem, dwBytes, wFlags ) : hNewMem 


Purpose 


Parameters 


198 


This function reallocates the global memory block specified 
by hMem by increasing or decreasing its size to the number 
of bytes specified by dwBytes. 


hMem is a handle to the global memory block to be reallo- 
cated. 


dwBytes is an unsigned long integer specifying the new size 
of the memory block. 


wk lags is an unsigned short integer flag specifying how to 
reallocate the global block. It can be one or more of the fol- 
lowing flags, joined with the bitwise OR operator: 


Value Meaning 
GMEM_ FIXED Memory is fixed (the 
default). , 


GMEM_ MOVEABLE Memory is moveable. If 
dwBytes is zero, this flag 
causes a previously fixed 
block to be freed or a previ- 
ously moveable object to be 
discarded (if the block’s 


reference count is zero). 


If dwBytes is nonzero and 


the block specified by hMem 
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is fixed, this flag allows the 
reallocated block to be 
moved to a new fixed loca- 
tion. (Note that the handle 
returned by GlobalReAlloc 
in this case may be different 
from the handle passed to 
the function.) 


GMEM_ ZEROINIT If the block is growing, the 
additional memory contents 
are initialized to zero. 


GMEM_ DISCARDABLE Memory is discardable. 


GMEM_ MODIFY Memory flags are modified. 
Can be used only with 
GMEM_ DISCARDABLE. 
The [nBytes parameter is 
ignored. 


GMEM_ NODISCARD Discarding of objects will 
not be performed in order to 
satisfy the allocation 
request. 


GMEM_~NOCOMPACT Memory compaction and dis- 
carding will not be per- 
formed in order to satisfy 
the allocation request. 


Return Value hNewMemis a handle to the reallocated global memory if 


the function is successful. hNewMem is NULL if the block 


cannot be reallocated. 


hNewMem is always identical to the hMem parameter, unless 
the GMEM_ MOVEABLE flag is used to allow movement of 
a fixed block to a new fixed location. 


GlobalSize ( hMem ): dwBytes 


Purpose 


Parameters 


This function retrieves the current size, in bytes, of the 
global memory block specified by hMem. 


hMem is a handle to a global memory block. 


Return Value dwBytes is an unsigned long integer specifying the size, in 


bytes, of the specified memory block. It is 0 if the given 
handle is not valid. 


199 


Microsoft Windows Reference Manual 


Notes 


The actual size of a memory block is sometimes larger than 
the size requested when the memory was allocated. 


GlobalUnlock ( hMem ): bResult 


Purpose 


Parameters 


Return Value 


This function unlocks the global memory block specified by 
hMem and decrements the block’s reference count by 1. The 
block is completely unlocked, and subject to moving or dis- 
carding, if the reference count is decremented to 0. 


hMem is a handle to the global memory block to be 
unlocked. 


bResult, a Boolean value, is nonzero if the block is still 
locked. It is zero if the block is now unlocked or if the 
hMem parameter was invalid. 


GlobalF lags ( hMem ): wFlags 


Purpose 


Parameters 
Return Value 


This function returns information about the specified global 
memory block. 


hMem is a handle to a global memory block. 


wFlags, an unsigned short integer, contains one of the fol- 
lowing memory allocation flags in the high-order byte: 


Value Meaning 

GMEM_ SWAPPED The block has been 
swapped. 

GMEM_ DISCARDED The block has been dis- 
carded. 

GMEM_ DISCARDABLE — The block is marked as dis- 
cardable. 


The low-order byte of wk lags contains the reference count of 
the block. The GMEM_LOCKCOUNT mask may be used 


to retrieve the lock count value from wFlags. 


LocalAlloc ( wFlags, wBytes ): hMem 


Purpose 
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This function allocates wBytes bytes of memory from the 
local heap. The memory block can be either fixed or mov- 
able as specified by wF lags. 


Parameters 
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wk lags is an unsigned short integer flag specifying how the 
memory is to be allocated. It can be any one of the follow- 
ing: 


Value Meaning 

LMEM_ FIXED Memory is fixed (the 
default). 

LMEM_ MOVEABLE Memory is moveable. 

LMEM_ ZEROINIT Memory contents are initial- 


ized to zero. 
LMEM_DISCARDABLE Memory is discardable. 
LMEM_ NODISCARD Discarding of objects will 


not be performed in order to 
satisfy the allocation 
request. 


LMEM_ NOCOMPACT Memory compaction and dis- 
carding will not be per- 
formed in order to satisfy 
the allocation request. 


wBytes is an unsigned short integer value specifying the 
total number of bytes to allocate. 


Return Value hMemis a handle to the newly allocated local memory block 


if the function is successful. Otherwise, it is NULL. 


LocalCompact ( wMinFree ) : wLargest 


Purpose 


Parameters 


This function generates wMinFree free bytes of memory by 
compacting, if necessary, the module’s local heap. The func- 
tion checks local heap for wMinF ree contiguous free bytes. 

If the bytes do not exist, LocalCompact compacts local 
memory by first moving all unlocked moveable blocks into 
high memory. If this does not generate the requested 
amount of space, the function discards discardable moveable 
blocks that are not locked down until the requested space is 
available. 


wMinF ree is an unsigned short integer value specifying the 
number of free bytes desired. If wMinF ree is 0, the function 
returns a value but does not compact memory. 
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Return Value wlLargest is an unsigned short integer number specifying the 
number of bytes in the largest block of free local memory. 
LocalDiscard ( hMem ): hOldMem 


Purpose This function discards the local memory block specified by 
hMem. 


Parameters hMemisa handle to a local memory block. 

Return Value hOldMem is NULL if the function is successful. Otherwise, it 
is equal to hMem. 

LocalF ree ( hMem ) : hOldMem 


Purpose This function frees the local memory block identified by 
hMem. 


Parameters hMemisa handle to the local memory block to be freed. 


Return Value hOldMem is NULL if the function is successful. Otherwise, 
it is equal to hMem. 


LocalLock ( hMem ) : pAddress 


Purpose This function locks the local memory block specified by 
hMem. The block is locked into memory at the given 
address and its reference count is incremented by one. 
Locked memory is not subject to moving or discarding. 


The block remains locked in memory until its reference 
count is decremented to zero using the LocalUnlock func- 
tion. 


Parameters hMemisa handle to the local memory block to be locked. 


Return Value pAddress is a short pointer to the first byte of memory in the 
local block if the function is successful. Otherwise, it is 


NULL. 

LocalFreeze ( Dummy ) 

Purpose This function prevents the local heap from being compacted. 
The LocalMelt function can later be called to allow com- 
pacting. 


Parameters Dummy is not used and can be set to zero. 


Return Value None. 
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LocalMelt ( Dummy ) 


This function allows compacting of the local heap. It can be 
used after LocalF reeze has been called. 


Purpose 


Parameters 
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Dummy is not used and can be set to zero. 


Return Value None. 


LocalReAlloc ( hMem, wBytes, wFlags ) : hNewMem 


Purpose 


Parameters 


This function reallocates the local memory block specified by 
hMem by increasing or decreasing its size to the number of 


bytes specified by wBytes. 


hMem is a handle to the local memory block to be reallo- 


cated. 


wBytes is an unsigned short integer value specifying the new 


size of the memory block. 


wF lags is an unsigned short integer value specifying how to 
allocate the local block. It consists of one or more of the fol- 
lowing flags, joined with the bitwise OR operator: 


Value 
LMEM_ FIXED 


LMEM_ MOVEABLE 


Meaning 


Memory is fixed (the 
default). 


Memory is moveable. If 
wBytes is zero, this flag 
causes a previously fixed 
block to be freed or a previ- 
ously moveable object to be 
discarded (if the block’s 


reference count is zero). 


If wBytes is nonzero and the 
block specified by hMem is 
fixed, this flag allows the 
reallocated block to be 
moved to a new fixed loca- 
tion. (Note that the handle 
returned by LocalReAlloc 
in this case may be different 
from the handle passed to 
the function.) 
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LMEM_ ZEROINIT If the block is growing, the 
additional memory contents 
are initialized to zero. 


LMEM_ DISCARDABLE Memory is discardable. 


LMEM_ MODIFY Memory flags are modified. 
Can be used with 
LMEM_ DISCARDABLE 
only. The nBytes parameter 
is ignored. 


LMEM_ NODISCARD Discarding of objects will 
not be performed in order to 
satisfy the allocation 
request. 


LMEM_ NOCOMPACT Memory compaction and dis- 
carding will not be per- 
formed in order to satisfy 
the allocation request. 


Return Value hNewMem is a handle to the reallocated global memory if 
the function is successful. hNewMem is NULL if the block 
cannot be reallocated. 


hNewMem is always identical to the hMem parameter, unless 
the LMEM_ MOVEABLE flag is used to allow movement of 
a fixed block to a new fixed location. 


LocalSize ( hMem ): wBytes 


Purpose This function retrieves the current size, in bytes, of the local 
memory block specified by hMem. 


Parameters hMemisa handle to a local memory block. 


Return Value wBytes is an unsigned short integer specifying the size, in 
bytes, of the specified memory block. It is NULL if the 
given handle is not valid. | 


Notes The actual size of a memory block is sometimes larger than 
the size requested when the memory was allocated. 
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LocalUnlock ( hMem ): bResult 


Purpose 


Parameters 
Return Value 


This function unlocks the local memory block specified by 
hMem and decrements the block’s reference count by 1. The 
block is completely unlocked, and subject to moving or dis- 
carding, if the reference count is decremented to zero. 


hMem is a handle to the local memory block to be unlocked. 


bResult, a Boolean value, is nonzero if the block is still 
locked. It is zero if the block is now unlocked or if the 
hMem parameter was invalid. 


LocalHandleDelta ( nNewDelta ) : nCurrentDelta 


Purpose 


Parameter 


Return Value 


This function sets the number of handle table entries to be 
allocated when the local heap manager runs out of handle 
table entries for local moveable objects. 


nNewDelta, a short integer value, is the number of handle 
table entries to be allocated (the “handle delta”). If 
nNewDelta is 0, the current handle delta is returned. 


nCurrentDelta is a short integer value specifying the current 


handle delta. 


LockData ( Dummy ) : hMem 


Purpose 


Parameters 
Return Value 


This function locks the current data segment in memory. 
The function is intended to be used in modules that have 
moveable data segments. 


Dummy is not used and can be set to zero. 


hMem is a handle to the locked data segment if the function 
is successful. Otherwise, it is NULL. 


UnlockData ( Dummy ) 


Purpose 


Parameters 


This function unlocks the current data segment. It is 
intended to be used by modules that have moveable data 
segments. 


Dummy is not used and can be set to 0. 


Return Value None. 
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LocalF lags ( hMem ): wk'lags 


Purpose This function returns information about the specified local 
memory block. 


Parameters hMemisa handle to a local memory block. 


Return Value wf lags, an unsigned short integer, contains one of the fol- 
lowing memory allocation flags in the high-order byte: 


Value Meaning 

LMEM_ DISCARDED The block has been dis- 
carded. 

LMEM_DISCARDABLE ~— The block is marked as dis- 
cardable. 


The low-order byte of wFlags contains the reference count of 
the block. The LMEM_LOCKCOUNT mask may be used to 


retrieve the lock count value from wf lags. 


4.4 ‘Task Functions 


This section describes the functions used to manage tasks. A task is any 
program that executes as an independent unit. All applications are exe- 
cuted as tasks. Each instance of an application is a task. 


GetCurrentTask ( ): hTask 


Purpose This function returns the handle of the currently executing 
task. 


Parameters None. 


Return Value hTaskis a task handle if the function is successful. Other- 
wise, it is NULL. | 


Yield ( ): bResult 


Purpose This function halts the current task and starts any waiting 
task. 


Parameters None. 
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Return Value bResult, a Boolean value, is nonzero if a waiting task is 


Note 


started. Otherwise, it is zero. 


Applications that contain windows should use a Peek Mes- 
sage, TranslateMessage, DispatchMessage loop rather 
than calling Yield directly. The PeekMessage loop handles 
message synchronization properly and yields at the 
appropriate times. 


SetPriority ( ATask, nChangeAmount ) : nNew 


Purpose 


Parameters 


This function modifies the task priority of the task specified 
by hTask by adding nChangeAmount to the current priority. 
The task priority can be modified to any value in the range 
-15 to 15. The highest task priority is -15, the lowest is 15. 
Task priority is initially set to 0. 


hTask is a handle to the task to be set. 


nChangeAmount is a short integer value specifying the 
amount to change the priority. 


Return Value nNew is a short integer value specifying the new priority of 


the task. 


4.5 Resource Manager Functions 


This section describes the functions used to find and load program 
resources from a Windows executable file. The functions let applications 
load cursors, icons,. bitmaps, strings, fonts, and other useful resources into 


memory. 


AddFontResource ( [pFilename ) : nFonts 


Purpose 


Parameters 


This function adds the font resource from the file named by 
lpFilename to the Windows font table. The fonts can subse- 
quently be used by any application. 


lpFilename is either a long pointer to a string naming the 
font resource file, or a handle to a loaded module in the 
low-order word and zero in the high-order word. If 
lpFtlename is a long pointer to the font resource file, the 
string must be null-terminated, have the DOS file name for- 
mat, and include the extension. 
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Return Value nFonts is a short integer specifying the number of fonts 
added. nF onts is zero if no fonts are loaded. 


Notes Any application that adds or removes fonts from the Win- 
dows font table should notify other windows of the change 
by sending a WM_FONTCHANGE message a Send- 
Message). The message should be sent to all window han- 
dles enumerated by the EnumWindows function. 


It is good practice to remove any font resource an applica- 
tion has added once the application is through with the 
resource. 


For a description of font resources, see the Microsoft Win- 
dows Programming Guide. 


RemoveF ontResource ( IpFilename ) : bSuccess 


Purpose This function removes an added font resource from the file 
named by /[pFtlename from the Windows font table. 


Parameters [pF tlename is either a long pointer to a string naming the 
font resource file, or a handle to a loaded module in the 
low-order word and zero in the high-order word. If 
lpFtlename is a long pointer to the font resource file, the 
string must be null-terminated, have the DOS file name for- 
mat, and include the extension. 


Return Value bSuccess, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


Notes Any application that adds or removes fonts from the Win- 
dows font table should notify other windows of the change 
by sending a WM_ FONTCHANGE message jasing Send- 
Message). The message should be sent to all window han- 
dles enumerated by the EnumWindows function. 


RemoveF ontResource may not actually remove the font 
resource. If there are outstanding references to the resource, 
the font resource remains loaded until the last referencing 
logical font has been deleted using the DeleteObject func- 
tion. 
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LoadBitmap ( hA/nstance, lpBitmapName ) : hBitmap 


Purpose 


Parameters 


Return Value 


Note 


This function loads the bitmap resource named by [pBitmap- 
Name from the executable file associated with the module 
hInstance. The function loads the resource into memory 
only if it has not been previously loaded. Otherwise, it 
retrieves a handle to the existing resource. 


hInstance is the instance handle of the module whose execut- 
able file contains the bitmap. 


lnpBitmapName is a long pointer to a character string naming 
the bitmap. The string must be a null-terminated ASCII 
string. 


hBitmap is a handle to the specified bitmap. It is NULL if no 
such bitmap exists. 


LoadBitmap assumes that the bitmap is stored in a 
device-independent format. The function stretches or 
compresses the bitmap to accommodate the system’s aspect 
ratio and resolution. 


The bitmap handle returned by LoadBitmap is automati- 
cally freed by Windows when the application terminates. 


LoadCursor ( Alnstance, lpCursorName ): hCursor 


Purpose 


This function loads the cursor resource named by [pCursor- 
Name from the executable file associated with the module 
specified by Alnstance. The function loads the cursor into 
memory only if it has not been previously loaded. Other- 
wise, it retrieves a handle to the existing resource. 


LoadCursor can also be used to access the predefined cur- 
sors used by Windows. The h/nstance argument must be set 
to NULL, and [pCursorName must be one of the following: 
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Parameters 


Name Cursor Type 

IDC_ ARROW Standard arrow cursor 

IDC_ IBEAM Text I-beam cursor 

IDC_ WAIT Hourglass cursor 

IDC_UPARROW Vertical arrow cursor 

IDC_ CROSS Crosshair cursor 

IDC_ SIZE Size box cursor (used when the user 
is sizing a window) 

IDC_ ICON Icon cursor (black box used for cur- 


sor in icon area) 


hInstance is the instance handle of the module whose execut- 
able file contains the cursor. 


lpCursorName is a long pointer to a character string naming 
the cursor resource. The string must be a null-terminated 


ASCII string. 


Return Value hCursor is a handle to the newly loaded cursor if the func- 


tion is successful. Otherwise, it is NULL. 


LoadIcon ( h/Jnstance, lpIconName ): hIcon 


Purpose 
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This function loads the icon resource named by [p/conName 
from the executable file associated with the module specified 
by Alnstance. The function loads the icon only if it has not 
been previously loaded. Otherwise, it retrieves a handle to 
the loaded resource. 


LoadIcon can also be used to access the predefined icons 
used by Windows. The Al/nstance argument must be set to 
NULL, and l[plconName must be one of the following: 


Parameters 


Return Value 
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Name Icon Type 

IDI APPLICATION Default application icon 

IDI_ HAND Hand-shaped icon (used in 
severe warning messages) 

IDI_ QUESTION Question mark (used in 


prompting messages) 
IDI.EXCLAMATION — Exclamation mark (used in 


warning messages) 


IDI ASTERISK Asterisk = in informative 


messages 


hInstance is the instance handle of the module whose execut- 
able file contains the icon. 


lp[conName is a long pointer to a character string naming 
the icon resource. The string must be a null-terminated 
ASCII string. 


hIconis a handle to an icon resource if the function is suc- 


cessful. Otherwise, it is NULL. 


LoadMenu ( A/nstance, lpMenuName ) : hMenu 


Purpose 


Parameters 


Return Value 


This function loads the menu resource named by 
lpMenuName from the executable file associated with the 
module specified by h/nstance. 


The function loads the menu only if it has not been previ- 
ously loaded. Otherwise, it retrieves a handle to the loaded 
resource. 


hInstance is the instance handle of the module whose execut- 
able file contains the menu. 


lpMenuName is a long pointer to a character string naming 
the menu resource. The string must be a null-terminated 


ASCII string. 


hMenu is a handle to a menu resource if the function is suc- 


cessful. Otherwise, it is NULL. 
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LoadString ( hAlnstance, wID, lpBuffer, nBufferMar ) : nSize 


Purpose 


Parameters 


This function loads a string resource identified by w/D from 
the executable file associated with module A/nstance. The 
function copies the string into the buffer pointed to by 
lpBuffer, and appends a terminating null character. 


hInstance is the instance handle of the module whose execut- 
able file contains the string resource. 


wlD is an unsigned short integer value identifying the string 
to load. 


lpBuffer is a long pointer to the buffer to receive the string. 


nBufferMaz is a short integer value specifying the maximum 
number of characters to be copied to the buffer. The string 
is truncated if it is longer than the buffer. 


Return Value nStze is a short integer value specifying the actual number of 


characters copied into the buffer. It is 0 if the string 
resource does not exist. 


LoadAccelerators ( hinstance, lpTableName ): hRes 


Purpose 


Parameters 


Return Value 


This function loads the accelerator table named by Ip Ta- 
bleName from the executable file associated with the module 
specified by hlnstance. 


The function loads the table only if it has not been previ- 
ously loaded. Otherwise, it retrieves a handle to the loaded 
table. 


hInstance is the instance handle of the module whose execut- 
able file contains the accelerator table. 


lp TableName is a long pointer to a string specifying the 
name of the accelerator table. The string must be a null- 
terminated ASCII string. 


hRes is a handle to the loaded accelerator table if the func- 
tion is successful. Otherwise, it is NULL. 


FindResource ( hI/nstance, lpName, lp Type ) : hResInfo 


Purpose 
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This function determines the location of a resource in the 
specified resource file. The lpName and [pType parameters 
define the name and resource type. 


Parameters 
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hinstance is the instance handle of the module whose execut- 
able file contains the resource. 


lp Name is a long pointer to a null-terminated string 
representing the name of the resource. 


lp Type is a long pointer to a null-terminated string 
representing the type name of the resource. For predefined 
resource types, the /p Type parameter should be one of the 
following values: 


Type Meaning 

RT_ CURSOR Cursor resource 
RT_ BITMAP Bitmap resource 
RT_ICON Icon resource 
RT_ MENU Menu resource 
RT_ DIALOG Dialog box 
RT_STRING String resource 
RT_ FONT Font resource 


RT_ ACCELERATOR Accelerator table 


Return Value hResInfo is a handle to the named resource. It is NULL if 


Notes 


the requested resource cannot be found. 


If the high-order word of lpName or Ip Type is 0, the low- 
order word specifies the integer ID of the name or type of 
the given resource. Otherwise, the parameters are long 
pointers to null-terminated strings. If the first character of 
the string is a pound sign (#), the remaining characters 
represent a decimal number that specifies the integer ID of 
the resource’s name or type. For example, the string 

“4 258” represents the integer ID 258. 


To reduce the amount of memory required for the resources 
used by an application, the application should refer to the 
resources by integer ID instead of by name. 
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LoadResource ( A/nstance, hResInfo ): hResData 


Purpose 


Parameters 


Return Value 


Note 


This function loads a resource identified by hResInfo from 
the executable file associated with the module Alnstance. 
The function loads the resource into memory only if it has 
not been previously loaded. Otherwise, it retrieves a handle 
to the existing resource. 


hInstance is the instance handle of the module whose execut- 
able file contains the resource. 


hResInfo is the resource handle associated with the desired 
resource. This handle is assumed to have been created using 
the FindResource function. 


hResData is a handle to the data associated with the 
resource. It is NULL if no such resource exists. 


The resource is not actually loaded until LockResource is 
called to translate the handle returned by LoadResource 
into a far pointer to the resource data. 


AllocResource ( Alnstance, hResInfo, nSize ): hMem 


Purpose 


Parameters 


Return Value 


This function allocates uninitialized memory for the passed 
resource. All resources must be initially allocated with this 
function. The LoadResource function calls this function 
before loading the resource. 


hInstance is the instance handle of the module whose execut- 
able file contains the resource. 


hResInfo is the resource handle associated with the desired 
resource. This handle is assumed to have been created using 
the FindResource function. 


nSize is a Short integer value specifying an override size. It 
is ignored if zero. 


hMem is a handle to the allocated memory. 


LockResource ( hResInfo ): lpResInfo 


Purpose 
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This function retrieves the absolute memory address of the 
loaded resource identified by hResInfo. The resource is 
locked in memory and the given address and its reference 
count is increased by one. The locked resource is not sub- 
ject to moving or discarding. 


Parameters 
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The resource remains locked in memory until its reference 
count is decreased to zero through calls to the 
FreeResource function. 


If the resource identified by hRes/nfo has been discarded, the 
resource handler function (if any) associated with the 
resource 1s called before LockResource returns. The 
resource handler function can recalculate and reload the 
resource if desired. After the resource handler function 
returns, LockResource makes another attempt to lock the 
resource and returns with the result. 


hResInfo is the resource handle associated with the desired 
resource. This handle is assumed to have been created using 
the FindResource function. 


Return Value IpResInfo is a long pointer to the first byte of the loaded 


resource if the resource was locked. Otherwise, lpRes/nfo is 
NULL. 


FreeResource ( hResData ): bF reed 


Purpose 


Parameters 


Return Value 


This function removes a loaded resource from memory by 
freeing the allocated memory occupied by that resource. 


FreeResource does not actually free the resource until the 
reference count is zero (that is, the number of calls to the 
function equals the number of times the application called 
LoadResource for this resource). This ensures that the 
data remains in memory while the application is still using 
it. 

hResData is a handle to the data associated with the 
resource. The handle is assumed to have been created using 
the LoadResource function. 


bF reed, a Boolean value, is nonzero if the function has failed 
and the resource has not been freed. It is zero if the function 
is successful. 


AccessResource ( hinstance, hResInfo ): hFile 


Purpose 


This function opens the specified resource file and moves the 
file pointer to the beginning of the specified resource, letting 
an application read the resource from the file into its own 
local memory space. The function supplies a DOS file han- 
dle that can be used in subsequent file read calls to load the 
resource. The file is opened for reading only. 
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Parameters 


Return Value 


Note 


Applications that use this function must close the resource 
file after reading the resource. 


hInstance is the module instance handle of the module whose 
executable file contains the resource. 


hResInfo is the resource handle associated with the desired 
resource. This handle is assumed to have been created using 
the FindResource function. 


hF tle is a DOS file handle to the specified resource file. It is 
—1 if the resource cannot be found. 


AccessResource can exhaust available DOS file handles 
and cause errors if the opened file is not closed after access- 
ing the resource. 


SizeofResource ( h/nstance, hResInfo ) : nBytes 


Purpose 


Parameters 


Return Value 


This function supplies the size in bytes of the specified 
resource. It is typically used with the AccessResource to 
prepare local memory to receive a resource from the file. 


hInstance is the instance handle of the module whose execut- 
able file contains the resource. 


hResInfo is the resource handle associated with the desired 
resource. This handle is assumed to have been created using 
the FindResource function. 


nBytes is a short integer value specifying the number of 
bytes in the resource. It is zero if the resource cannot be 
found. 


SetResourceHandler ( hinstance, lp Type, lpLoadFunc ) : lpLoadF unc 


Purpose 
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This function sets up a function to load resources. It is used 
internally by Windows to implement calculated resources. 
Applications may find this function useful for handling their 
own resource types, but its use is not required. 


The LockResource function calls the lpLoadFunc whenever 
it fails to lock a resource having the type given by IpType. 
The [pLoadF unc receives information about the resource to 
be locked and can process that information as desired. 

After the [pLoadF unc returns, LockResource attempts the 
lock the resource once more. 


Parameters 
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hInstance is the instance handle of the module whose execut- 
able file contains the resource. 


lp Type is a long pointer to a short integer specifying a 
resource type. 


lnLoadF unc is a long pointer to the user-supplied function. 


Return Value lpLoadFunc is the long pointer to the user-supplied function. 


Note 


The user-supplied function must have the form: 
lpLoadFunc( hMem, hInstance, hResInfo) 


where hMem is a handle to a stored resource, h/nstance is 
the instance handle of the module whose executable file con- 
tains the resource, and AResI/nfo is the resource handle asso- 
ciated with the desired resource (assumed to have been 
created using FindResource). 


hMem is NULL if the resource has not yet been loaded. If an 
attempt to lock a block specified by hMem fails, the resource 
has been discarded and must be reloaded. 


4.6 String Translation Functions 


This section describes functions used to translate strings from one charac- 
ter set to another, to convert the case of strings, and to find adjacent char- 
acters in a string. 


AnsiToOem ( [pAnstStr, lpOemStr ) : bTranslated 


Purpose 


Parameters 


This function translates the string pointed to by l[pAnstStr 
from the ANSI character set to the OFM-defined character 
set. 


lpAnstStr is a long pointer to a null-terminated string of 
characters from the ANSI character set. 


lp OemStr is a long pointer to the location to which the 
translated string is copied. lpOemStr can be the same as 
lpAnstStr to translate the string in place. 


Return Value bTranslated, a Boolean value, is nonzero if all characters in 


the ANSI string have been translated into equivalent char- 
acters in the OEM character set. It is zero if one or more 
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characters in the ANSI string had no direct equivalent in the 
OEM character set. In such cases, an arbitrary OEM char- 
acter is selected for the translation. 


OemToAnsi ( [pOemSir, IlpAnstStr ) : Translated 


Purpose 


Parameters 


This function translates the string pointed to by lpOemStr 
from the OEM-defined character set to the ANSI character 
set. 


lp OemStr is a long pointer to a null-terminated string of 
characters from the OKM-defined character set. 


lpAnstStr is a long pointer to the location to which the 
translated string is copied. lpAnsiStr can be the same as 
lpOemStr to translate the string in place. 


Return Value 6Translated, a Boolean value, is nonzero if all characters in 


the OEM string have been translated into equivalent charac- 
ters in the ANSI character set. It is zero if one or more 
characters in the OEM string had no direct equivalent in the 
ANSI character set. In such cases, an arbitrary ANSI char- 
acter is selected for the translation. 


AnsiUpper ( [pStr ) : cChar 


Purpose 


Parameter 


This function converts a string or a character to upper case. 


lpStr is a long pointer to a null-terminated string, or it is a 
long integer value whose high-order word contains zero and 
low-order word a single character. 


Return Value cChar, a byte value, is the converted character if a single 


character is given. Otherwise, cChar is a long pointer and 
equal to [pStr. 


AnsiLower ( [pSitr ) : cChar 


Purpose 


Parameter 


This function converts the given string to lower case. 


lp Str is a long pointer to a null-terminated string, or it is a 
long integer value whose high-order word contains zero and 
whose low-order word contains a single character. 


Return Value cChar, a byte value, is the converted character if a single 
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character is given. Otherwise, cChar is a long pointer and 
equal to [pStr. 
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AnsiNext ( [pCurrentChar ) : lpNeztChar 


Purpose 


Parameter 


Return Value 


Note 


This function moves to the next character in a string. 


lp CurrentChar is a long pointer to a character in a null- 
terminated string. 


lp NextChar is a long pointer to the next character in the 
string, or if there is no next character, to the null character 
at the end of the string. 


AnsiNext is used to move through strings whose characters 
are two or more bytes each (for example, strings containing 
characters from a Japanese character set). 


AnsiPrev ( [pStart, lpCurrentChar ) : lpPrevChar 


Purpose 


Parameters 


Return Value 


Note 


This function moves to the previous character in a string. 
lp Start is a long pointer to the beginning of the string. 


lp CurrentChar is a long pointer to a character in a null- 
terminated string. 


lpPrevChar is a long pointer to the previous character in the 
string, or to the first character in the string if lpCurrentChar 
is equal to [pStart. 


AnsiPrev is used to move through strings whose characters 
are two or more bytes each (for example, strings containing 
characters from a Japanese character set). 


4.7 Atom Manager Functions 


This section describes the functions used to create and use atoms. An atom 
is an integer number that uniquely identifies a character string stored in 
the atom table. Atoms are useful in applications that use many character 


strings. 


InitAtomTable ( nSize ): bResult 


Purpose 


This function initializes an atom hash table and sets its size 
to nSize. If this function is not called, the atom hash table 
size is set to 37 by default, limiting the maximum number of 
atoms to 37. 


If used, this function should be called before any other atom 
manager function. 
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Parameter 


Return Value 


nSize is a short integer value specifying the size (in table 
entries) of the atom hash table. 


bResult, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


AddAtom ( [pString ) : nAtom 


Purpose 


Parameter 


Return Value 


Notes 


This function adds the character string pointed to by 
lpString to the atom table and creates a new atom that 
uniquely identifies the string. The atom can be used in a 
subsequent GetAtomName function to retrieve the string 
from the atom table. 


AddAtom stores no more than one copy of a given string in 
the atom table. If the string is already in the table, the 
function returns the existing atom value and increments the 
string’s reference count by one. 


lpString is a long pointer to the character string to be added 
to the table. The string must be an null-terminated ASCII 
string. 

nAtom, a short integer value, is the newly created atom if 
the function is successful. Otherwise, it is NULL 


The atom values returned by AddAtom are in the range 
C000 to FFFF (hexadecimal). 


DeleteAtom ( nAtom ): nOldAtom 


Purpose 


Parameter 


This function deletes an atom and, if the atom’s reference 
count is zero, removes the associated string from the atom 
table. 


An atom’s reference count specifies the number of times the 
atom has been added to the atom table. AddAtom incre- 
ments the count on each call; DeleteAtom decrements the 
count on each call. DeleteAtom removes the string only if 
the atom’s reference count is zero. 


nAtom is a short integer value specifying the atom and char- 
acter string to be deleted. 


Return Value nOldAtom, a short integer value, is NULL if the function is 
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successful. It is equal to nAtom if the function failed and the 
atom has not been deleted. 
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FindAtom ( [pString ): nAtom 


Purpose 


Parameter 


Result 


This function searches the atom table for the character 
string pointed to by [pString and retrieves the atom associ- 
ated with that string. 


lpString is a long pointer to the character string to be 
searched for. The string must be a null-terminated ASCII 
string. 

nAtom, a short integer value, is the atom associated with the 
given string. It is NULL if the string is not in the table. 


GetAtomName ( nAtom, lpBuffer, nSize): nLength 


Purpose 


Parameters 


Return Value 


This function retrieves a copy of the character string associ- 
ated with nAtom and places it in the buffer pointed to by 
lnBuffer. The nStze specifies the maximum size of the buffer. 


nAtom is a short integer value identifying the character 
string to be retrieved. 


lpBuffer is a long pointer to the buffer to receive the charac- 
ter string. 


nSize is a short integer value specifying the maximum size in 
bytes of the buffer. 


nLength is a short integer value specifying the actual number 
of bytes copied to the buffer. It is 0 if the specified atom is 
not valid. 


MAKEINTATOM ( wilnteger ): nAtom 


Purpose 


Parameters 


Return Value 


This macro creates an integer atom that represents a char- 
acter string of the form 


# digits 


where digits are the decimal digits of the integer. Integer 
atoms created by this macro can be added to the atom table 
using the AddAtom function. 


winteger is an unsigned short integer value specifying the 
numeric value of the atom’s character string. 


nAtom, a short integer value, is the atom created for the 
given integer. 
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Notes The DeleteAtom function always succeeds for integer 
atoms, even though it does nothing, and the GetAtom- 
Name function always returns the string form of the 
integer atom (e.g. “#£ 123”). 


4.8 Windows Initialization File Functions 


This section describes the functions used to read from and write to the 
Windows initialization file. The Windows initialization file is a special 
ASCII file that contains “keyname-value” pairs that represent runtime 
options for applications. 


GetProfileInt ( [pApplicationName, lpKeyName, nDefault ) : nKey Value 


Purpose This function retrieves the value of an integer key from the 
the Windows initialization file WIN.INI. The function 
searches the Windows initialization file for a key matching 
the name specified by lpKeyName under the application 
heading specified by [pApplicattonName. 


An integer entry in the Windows initialization file must 
have the following form: 


[| Application-Name | 
Key-Name = value 


where value is the key’s integer value. 


Parameters  IlpApplicationName is a long pointer to a character string 
naming the application. The string must be a null- 
terminated ASCII string. 


lpKeyName is a long pointer to a character string naming a 
key. The string must be a null-terminated ASCII string. 


nDefault is a short integer value specifying the default value 
for the given key if the key cannot be found in the Windows 
initialization file. 


Result nK ey Value is a short integer value specifying the value of 
the given key if the key exists. Otherwise, nKey Value is 
equal to nDefault. 
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GetProfileString ( [pApplicattonName, lpKeyName, lpDefault, lpReturned- 


Purpose 


Parameters 


String, nSize): nLength 


This function copies a character string from the user profile, 
WIN.INI, into the buffer pointed to by lpReturnedString. 
The function searches the Windows initialization file for a 
key matching the name specified by lpKeyName under the 
application heading specified by lpApplicationName. If the 
key is found, the corresponding string is copied to the 
buffer. If the key does not exist, the default character 
string, [pDefault, is copied. 


A string entry in the Windows initialization file must have 
the following form: 


[ Application-Name | 
Key-Name = string 


where string is an ASCII string. 


If lpKeyName is NULL, GetProfileString enumerates all 
keynames associated with [pApplicationName by filling the 
location pointed to by lpReturnedString with a list of key- 
names (not values). Each keyname in the list is terminated 
with a null character. The last string in the list is ter- 
minated with two null characters. GetProfileString 
returns the length of the list, up to, but not including, the 
final null. 


lpApplicationName is a long pointer to a character string 
naming the application. The string must be a null- 
terminated ASCII string. 


lnKeyName is a long pointer to a character string naming a 
key. The string must be a null-terminated ASCII string. 


lpDefault is a long pointer to the character string to be used 
if the given key does not exist. It must be a null-terminated 
ASCII string. : 


lnpReturnedString is a long pointer to the buffer to receive the 
character string. 


nSize is a short integer value specifying the maximum 
number of bytes to be copied to the buffer. If the actual 
string is longer, it is truncated. 
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Return Value nLength is a short integer value specifying the actual number 
of characters copied to IpReturnedString. 


Notes GetProfileString is not case-dependent, so the strings in 
lpApplticattonName and lpKeyName may be in any combina- 
tion of uppercase and lowercase letters. 


WriteProfileString ( [pApplicationName, lpKeyName, IpString ): bResult 


Purpose This function copies the character string pointed to b 
lpString into the Windows initialization file, WIN.INI. This 
function searches the Windows initialization file for the key 
named by [pKeyName under the application heading 
specified by lpApplicationName. If there is no match, it adds 
a new string entry to the user profile. If there is a matching 
key, the function replaces that key’s value with [pString. 


If there is no application field for lpApplicattonName, this 
function creates a new application field and places an 
appropriate key-value line in that field of the Windows ini- 
tialization file. 


A string entry in the Windows initialization file has the fol- 
lowing form: 


[| Application-Name | 
Key-Name = string 


where string is an ASCII string. 


Parameters  lpApplicattonName is a long pointer to a character string 
naming the application. The string must be a null- 
terminated ASCII string. 


lpKeyName is a long pointer to a character string naming 
the desired key. The string must be a null-terminated 


ASCII string. 


lp Value is a long pointer to the string to be copied to the 
file. The string must be a null-terminated ASCII string. 


Return Value bResult, a Boolean value, is nonzero if the function is suc- 
cessful. Otherwise, it is zero. 


Notes Applications that make changes to the WIN.INI file in sec- 
tions that are also accessed by other applications must send 
a WM_ WININICHANGE message to all applications in the 


system. 
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4.9 Debugging Function 


This section describes the function used to provide system information on 
program errors. 


FatalExit ( Code): Result 


Purpose 


Parameters 


This function displays the current state of Windows and 
prompts for instructions on how to proceed. The display 
includes an error code, Code, followed by a symbolic stack 
trace, showing the flow of execution up to the point of call. 


The function prompts for user response to an “Abort, Break 
or Ignore” message. FatalExit processes the response as fol- 
lows: 


a — terminate Windows 
b — simulate an NMI interrupt to enter the debugger 
i — return to the caller 


The function is intended to be called whenever Windows 
detects a fatal error. All input and output is through the 
computer’s auxiliary port (AUX). 


Code is an integer value specifying the error code to be 
displayed. 


Return Value Result, an integer value, is returned only if the user chose to 


ignore the fatal error. 


4.10 Communication Functions 


This section describes the functions used to carry out communications 
through the system’s serial and parallel I/O ports. ' 


OpenComm ( lpComName, ninQueue, nOutQueue ): nCid 


Purpose 


This function opens a communication device and assigns a 
nC1d handle to it. The communication device is initialized 
to a default configuration. The SetCommState function 
should be used to initialize the device to alternate values. 
The function allocates space for “receive” and “transmit” 
queues. The queues are used by the interrupt-driven 
transmit/receive software. 
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Parameters 


lnComName is a long pointer to a string that contains 
“COMn” or “LPTn”, where n is allowed to range from 1 to 
the number of communication devices available for the type 


of 1/O port. 


ninQueue is a short integer value specifying the size of the 
receive queue. 


nOutQueue is a short integer value specifying the size of the 
transmit queue. 


Return Value nCtd is a short integer value identifying the opened com- 


munication device. If an error occurs, nCid is one of the fol- 
lowing negative error values: 


Value Error 

IE_ BADID Invalid or unsupported ID 
IE_ OPEN Device already open 

[E_ NOPEN Device not open 

IE_ MEMORY Unable to allocate queues 
JE_ DEFAULT Error in default parameters 
JE_ HARDWARE Hardware not present 

JE_ BY TESIZE Invalid byte size 

IE_ BAUDRATE Unsupported baud rate 


CloseComm ( nCid ) : nResult 


Purpose 


Parameters 


Return Value 
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This function closes the communication device specified by 
nCid and frees any memory allocated for the device’s 
transmit and receive queues. All characters in the output 
queue are sent before the communications device is closed. 


nCrd is a short integer value specifying the device to be 
closed. | 


nftesult is a short integer value specifying the result of the 
function. It is 0 if the device is closed. It is negative if an 
error occurred. 
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ReadComm ( nCid, IpBuf, nSize ) : nBytes 


Purpose 


Parameters 


Return Value 


This function attempts to read nSize characters from the 
communication device specified by nCid and copy the char- 
acters into the buffer pointed to by I[pBuf. 


nCid is a short integer value specifying the communication 
device to be read. 


lp Buf is a long pointer to the buffer to receive the characters 
read. 


nSize is a short integer value specifying the number of char- 
acters to read. 


nBytes is a short integer value specifying the number of 
characters actually read. It is less than nSize only if the 
number of characters in the receive queue is less than nSize. 
If it is equal to nSize, additional characters may be queued 
for the device. If nBytes is 0, no characters are present. 


On an error, nBytes is set to a value less than 0, making the 
absolute value of nBytes the actual number of characters 
read. The cause of the error can be determined by using the 
GetCommError function to retrieve the error code and 
status. Since errors can occur when no bytes are present, if 
nBytes is 0, the GetCommError function should be used 
to ensure that no error occurred. 


For parallel I/O ports, nBytes will always be 0. 


WriteComm ( nCid, lpBuf, nSize ) : nBytes 


Purpose 


Parameters 


Return Value 


This function writes nSize bytes to the communication 
device specified by nCid from the buffer pointed to by IpBuf. 


nCid is a short integer value specifying the device to receive 
the characters. 


lp Buf is a long pointer to the buffer containing the charac- 
ters to be written. 


nSize is a short integer value specifying the number of char- 
acters to write. 


nBytes is a short integer value specifying the number of 
characters actually written. On an error, nBytes is set to a 
value less than 0, making the absolute value of nBytes the 
actual number of characters written. The cause of the error 
can be determined by using the GetCommError function 
to retrieve the error code and status. 
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UngetCommChar ( nCid, cChar ): nResult 


Purpose 


Parameters 


This function places the character cChar back into the 
receive queue, making this character the first to be read on a 
subsequent read from the queue. 


Consecutive calls to UngetCommChar are not allowed. 
The character placed back into the queue must be read 
before attempting to place another. 


nCid is a short integer value specifying the communication 
device to receive the character. 


cChar is the byte value of the character to be put into the 
recelve queue. 


Return Value nfesult, a short integer value, is zero if the function was suc- 


cessful. If an error occurred, nResult is negative. 


TransmitCommChar ( nCid, cChar ) : nResult 


Purpose 


Parameters 


This function marks the character cChar for immediate 
transmission by placing it at the head of the transmit queue. 


nCid is a short integer value specifying the communication 
device to receive the character. 


cChar is the byte value of the character to be written. 


Return Value nfFesult is a short integer value specifying the result of the 


function. It is 0 if the function is successful. It is negative if 
the character cannot be transmitted. A character cannot be 
transmitted if the character specified by the previous 
TransmitCommChar has not yet been sent. 


BuildCommDCB ( IpDef, lpDCB) : nResult 


Purpose 


Parameters 
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This function translates the definition string specified by 
lpDefinto appropriate device control block codes and places 
these codes into the block pointed to by [pDCB. 


lpDef is a long pointer to a null-terminated string specifying 
the device control information for a device. The string must 


have the same form as the MS-DOS MODE command line 
argument. 


lpDCB is a long pointer to a data structure having DCB 
type. 
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Return Value nfesult is a short integer value specifying the result of the 


function. It is 0 if the string is translated. It is negative if 
an error occurs. 


GetCommState ( nCid, lpDCB): nResult 


Purpose 


Parameters 


This function fills the buffer pointed to by IpDCB with the 
device control block of the communication device specified 
by nCid. 


nCtd is a short integer value specifying the device to be 
examined. 


lnDCB is a long pointer to a data structure having DCB 
type. 


Return Value nfesult, a short integer value, is zero if the function was suc- 


cessful. If an error occurred, nResult is negative. 


SetCommState ( IpDCB): nResult 


Purpose 


Parameters 


This function sets a communication device to the state 
specified by the device control block pointed to by [pDCB. 
The device to be set must be identified by the JD field of the 


control block. 


This function reinitializes all hardware and control as 
defined by [pDCB, but does not empty transmit or receive 
queues. 


lyDCB is a long pointer to a data structure having DCB 
type. 


Return Value nfesult, a short integer value, is zero if the function is suc- 


cessful. If an error occurred, nResult is negative. 


GetCommError ( nCid, IpStat ) : nError 


Purpose 


Parameters 


This function fills the status buffer pointed to by IpStat with 
the current status of the communication device specified by 
nCid. It also returns the error codes that have occurred 
since the last GetCommError call (see Table 4.1 for error 
codes). If lpStatis NULL, only the error code is returned. 


nCtd is a short integer value specifying the communication 
device to be examined. 


lynStat is a long pointer toa COMSTAT data structure to 
receive the device status. 
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Return Value nError is a short integer value specifying the error codes 
returned by the most recent communications function. 


Table 4.1 


Communications Driver Error Codes 


Code 
CE_ MODE 


CE_ RXOVERRUN 


CE_ OVERRUN 


CE_ RXPARITY 
CEK_ FRAME 
CE_ BREAK 
CE. CTSTO 


CE_ DSRTO 


CE_ RLSDTO 


CE_ TXFULL 


CE_ PTO 


CE_ IOE 


CE_ DNS 
CEH_ OOP 
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Meaning 


Requested mode is not supported, or the given nCid is 
invalid. If set, this is the only valid error. 


Receive queue overflow. There was either no room in 
the input queue or a character was received after the 
EofChar was received. 


A character was not read from the hardware before the 
next character arrived. The character was lost. 


The hardware detected a parity error. 
The hardware detected a framing error. 
The hardware detected a break condition. 


Clear To Send timeout. CTS was low for the duration 
specified by Cts Timeout while trying to transmit a 
character. 


Data Set Ready timeout. DSR was low for the duration 
specified by Dsr Timeout while trying to transmit a 
character. 


Receive Line Signal Detect timeout. RLSD was low for 
the duration specified-by RisdTimeout while trying to 
transmit a character. 


The transmit queue was full while trying to queue a 
character. 


Timeout occurred while trying to communicate with a 
parallel device. 


An I/O error occurred while trying to communicate with 
a parallel device. 


The parallel device was not selected. 
The parallel device signaled it was out of paper. 
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SetCommEvent Mask ( nCid, nEvtMask ) : lpEvent 


This function enables and retrieves the event mask of the 
communication device specified by nCid. The bits of the 
nEvtMask parameter define which events are to be enabled. 
The return value points to the current state of the event 


Purpose 


Parameters 


mask. 


nCid is a short integer value specifying the communication 
device to be examined. 


nivtMask is a short integer value whose bits specify which 
events are to be enabled. It can be any combination of the 


following: 
Value 
EV_RXCHAR 


EV_RXFLAG 


EV_ TXEMPTY 
EV_CTS 

EV_ DSR 

EV_ RLSD 


EV_ BREAK 
BV_ ERR 


EV_ RING 
EV_PERR 


Meaning 


Set when any character is received and 
placed in the receive queue. 


Set when the event character is 
received and placed in the receive 
queue. The event character is specified 
in the device’s control block. 


Set when the last character in the 
transmit queue is sent. 


Set when the Clear To Send (CTS) sig- 


nal changes state. 


Set when the Data Set Ready (DSR) 


signal changes state. 


Set when the Receive Line Signal 
Detect (RLSD) signal changes state. 


Set when a break is detected on input. 


Set when a line status error occurs. 
Line status errors are 


CE_ RXPARITY, CE_ OVERRUN, 
and CE_ FRAME. 


Set when ring indicator is detected. 


Set when a printer error is detected on 
a parallel device. Printer errors are 
CE_ PTO, CE_IOE, CE_ DNS, and 
CE_ LOOP. 
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Return Value IpEvent is a long pointer to the event mask, a short integer. 
Each bit in the event mask specifies whether or not a given 
event has occurred. A bit is 1 if the event has occurred. 


GetCommEventMask ( nCid, nEvtMask ) : nEvent 


Purpose This function retrieves the value of the current event mask, 
then clears the mask. This function must be used to prevent 
loss of an event. 


Parameters nCidis a short integer value specifying the communication 
device to be examined. 


nEvtMask is a short integer value whose bits specify which 
events are to be enabled. It can be any combination of the 
following: 


Value Meaning 
EV_RXCHAR Set when any character is received 


and placed in the receive queue. 


EV_RXFLAG Set when the event character is 
received and placed in the receive 
queue. The event character is 


specified in the device’s control 
block. 


EV_ TXEMPTY Set when the last character in the 


transmit queue is sent. 


EV_CTS Set when the Clear To Send (CTS) 
signal changes state. 

EV_ DSR Set when the Data Set Ready (DSR) 
signal changes state. 

EV_RLSD Set when the Receive Line Signal 
Detect (RLSD) signal changes state. 

EV_ BREAK Set when a break is detected on 
input. 

EV_ ERR Set when a line status error occurs. 


Return Value n&vent is a short integer value specifying the current event 
mask value. Each bit in the event mask specifies whether or 
not a given event has occurred. A bit is 1 if the event has 
occurred. 


232 


System Resource Functions 


FlushComm ( nCid, nQueue ) : nResult 


Purpose 


Parameters 


This function flushes all characters from the transmit or 
receive queue of the communication device specified by nCid. 
The nQueue parameter specifies which queue is to be 


flushed. 


nCid is a short integer value specifying the communication 
device to be flushed. 


nQueue is a short integer value specifying which queue is to 
be flushed. It can be one of the following: 


0 - Flush transmit queue 
1 - Flush receive queue 


Return Value nfesult is a short integer value specifying the result of the 


function. It is 0 if it is successful. It is negative if nCid is 
not a valid device, or if nQueue is not a valid queue. 


SetCommBreak ( nCid ): nResult 


Purpose 


Parameters 


Return Value 


This function suspends character transmission and places 
the transmission line in a break state until the Clear- 


CommBreak function is called. 


nCid is a short integer value specifying the communication 
device to be suspended. 


nResult is a short integer value specifying the result of the 
function. It is 0 if it is successful. It is negative if nCid is 
not a valid device. 


ClearCommBreak ( nCid ) : nResult 


Purpose 


Parameters 


This function restores character transmission and places the 
transmission line in a nonbreak state. 


nCid is a short integer value specifying the communication 
device to be restored. 


Return Value nesult is a short integer value specifying the result of the 


function. It is 0 if it is successful. It is negative if nCtd is 
not a valid device. 
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EscapeCommFunction ( nCid, nFunc ): nResult 


Purpose This function directs the communication device specified by 
nCtd to carry out the extended function specified by nFunc. 


Parameters nCtdis ashort integer value specifying the communication 
device to carry out the extended function. 


nl'unc is a short integer value specifying the function code 
of the extended function. It can be any one of the following: 


Value 
SETXOFF 


SETXON 


SETRTS 


CLRRTS 
SETDTR 


CLRDTR 


RESETDEV 


Meaning 


Causes transmission to behave as if an 
XOFF character has been received. 


Causes transmission to behave as if an 
XON character has been received. 


Asserts the Request To Send (RTS) sig- 


nal. 
Clears the Request To Send (RTS) signal. 


Asserts the Data Terminal Ready (DTR) 
signal. 


Clears the Data Terminal Ready (DTR) 


signal. 


Reset the device if possible. 


Return Value nfesult is a short integer value specifying the result of the 
function. It is 0 if it is successful. It is negative if nF'unc is 
not a valid function code. 
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4.11 Sound Functions 


This section describes the functions used to create sounds and music for the 
system’s sound generator. 


OpenSound ( ): nVoices 


Purpose 


Parameters 
Return Value 


This function opens access to the play device and prevents 
subsequent opening of the device by other applications. 


None. 


nVotces is a short integer value specifying the number of 
voices available. It is S_-SERDVNA if the play device is in 
use. It is S_ EROFM if insufficient memory is available. 


CloseSound ( ) 


Purpose 


Parameters 


This function closes access to the play device and frees the 
device for opening by other applications. CloseSound 
flushes all voice queues and frees any buffers allocated for 
these queues. 


None. 


Return Value None. 


Set VoiceQueueSize ( nVoice, nBytes ): nResult 


Purpose 


Parameters 


Return Value 


This function allocates nBytes bytes for the voice queue 

specified by nVozce. If the queue size is not set, the default 
is 192 bytes, room for about 32 notes. All voice queues are 
locked in memory. The queues cannot be set while music is 


playing. 
nVotce is a short integer value specifying a voice queue. 


nBytes is a short integer value specifying the number of 
bytes in the voice queue. 


nfesult is a short integer value specifying the result of the 
function. It is zero if the function is successful. On a error, 
it is one of the following: 


S_ SEROFM Out of memory 
S_ SERMACT Music active 
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Set VoiceAccent ( nVoice, nTempo, nVolume, nMode, nPitch ) : nResult 


Purpose 


Parameters 


Return Value 
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This function places an accent (tempo, volume, mode, and 
pitch) in the voice queue nVoice. The new accent replaces 
the previous accent and remains in effect until another 
accent is queued. An accent is not counted as a note. 


An error occurs if there is insufficient room in the queue; 
Set VoiceAccent always leaves space for a single syne mark 
in the queue. If nVotce is out of range, Set VoiceAccent is 
ignored. 


n Voice is a short integer value specifying a voice queue. The 
first voice queue is numbered 1. 


nTempo is a short integer value specifying the number of 
quarter notes played per minute. It can be any value in the 
range 32 to 255. The default is 120. 


n Volume is a short integer value specifying the volume level. 
It can be any value in the range 0 (lowest volume) to 255 
(highest volume). 


nMode is a sort integer value specifying how the notes are to 
be played. It can be any one of the following: 


Value Meaning 

S_ LEGATO Note is held for the full duration 
and blended with the beginning of 
the next. 


S_ STACCATO Note is held for only part of the 
duration, creating a pronounced 
stop between it and the next note. 


S_ NORMAL Note is held for the full duration, 
coming to a full stop before the next 
note starts. 


nPitch is a short integer value specifying the pitch of the 
notes to be played. It can be any value in the range 0 to 83. 
The pitch value is added to the note value using modulo 84 
arithmetic. 


nResult is a short integer value specifying the result of the 
function. It is zero if the function is successful. On an error 
it is one of the following: 
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Value Error 


S-SERQFUL Queue full 
S_SERDVL Invalid volume 
S_SERDTP Invalid tempo 
S_SERDMD Invalid mode 


Set VoiceEnvelope ( nVoice, nShape, nRepeat ): nResult 


Purpose 


Parameters 


This function queues the envelope (wave shape and repeat 
count) in the voice queue specified by nVotce. The new 
envelope replaces the previous one and remains in effect 
until the next Set VoiceEnvelope call. An envelope is not 
counted as a note. 


An error occurs if there is insufficient room in the queue; 
Set VoiceEnvelope always leaves space for a single sync 
mark in the queue. If nVotce is out of range, Set VoiceEn- 
velope is ignored. 


n Voice is a short integer value specifying the voice queue to 
receive the envelope. 


nShape is a short integer value specifying an index to an 
OEM wave shape table. 


nftepeat is a short integer specifying the number of repeti- 
tions of the shape during the duration of one note. 


Return Value nResult is a short integer value specifying the result of the 


function. It is zero if the function is successful. On an error, 
it is one of the following: 


Value Error 


S-SERQFUL Queue full 
S_SERDSH _ Invalid shape 
S_SERDRC Invalid repeat count 
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SetSoundNoise ( nSource, nDuration ) : nResult 


Purpose This function sets the source and duration of a noise in the 
noise hardware of the play device. 


Parameters nSource is a short integer value specifying the noise source. 
It can be any one of the following values: 


Value Meaning 

S— PERIOD512 Source frequency is N/512 
(high pitch), hiss is less coarse 

S_ PERIOD1024 Source frequency is N/1024 

S— PERIOD2048 Source frequency is N/2048 
(low pitch), hiss is coarser 

S— PERIODVOICE Source frequency from voice 
channel 3 

S— WHITE512 Source frequency is N/512 
(high pitch), hiss is less coarse 

S— WHITE1024 Source frequency is N/1024 

S— WHITE2048 Source frequency is N/2048 
(low pitch), hiss is coarser 

S— WHITEVOICE Source frequency from voice 
channel 3 


nDuratton is a short integer value specifying the duration of 
the noise in clock tics. 


Return Value nfesult is a short integer value specifying the result of the 
function. It is zero if the function is successful. If the source 


is invalid, it is S_-SERDSR. 


Set VoiceNote ( nVotce, nValue, nLength, nCdots ): nResult 


Purpose This function queues a note with the qualities given by 
nValue, nLength, and nCdots in the voice queue specified by 
nVotce. An error occurs if there is insufficient room in the 
queue. The function always leaves space in the queue for a 
single sync mark. 


Parameters nVotce is a short integer value specifying the voice queue to 
receive the note. If nVozce is out of range, Set VoiceNote is 
ignored. 
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nValue is a short integer value specifying one of 84 possible 
notes (7 octaves). If nValue is zero, a rest is assumed. 


nLength is a short integer value specifying the reciprocal of 
the duration of the note. For example, 1 specifies a whole 
note, 2 a half note, 4 a quarter note, and so on. 


nCdots is a sort integer value specifying the duration of the 
note in dots. The duration is equal to 
nLength+(nCdots*3/2). 


Return Value nResult is a short integer value specifying the result of the 


function. It is zero if the function is successful. On an 
error, it is one of the following: 


Value Error 


S_SERQFUL Queue full 
S_SERDNT _ Invalid note 
S_SERDLN _ Invalid note length 
S_SERDCC Invalid Cdot count 


Set VoiceSound ( nVoice, I[Frequency, nDuratton ) : nResult 


Purpose 


Parameters 


This function queues the sound frequency and duration in 
the voice queue specified by nVotce. 


nVotce is a short integer value specifying a voice queue. The 
first voice queue is numbered 1. 


[Frequency is a long integer specifying the frequency. The 
high-order word contains the frequency in Kilohertz, and the 
low-order word contains the fractional frequency. 


nDuration is a short integer specifying the duration of the 
sound in clock ticks. 


Return Value nResult is a short integer value specifying the result of the 


function. It is zero if the function is successful. On an error, 
it is one of the following: 
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Value Error 


S_SERQFUL Queue full 
S_SERDFQ _ Invalid frequency 
S_SERDDR _ Invalid duration 
S-SERDVL Invalid volume 


StartSound ( }: nfesult 


Purpose This function starts play in each voice queue. The Start- 
Sound function is not destructive, so may be called any 
number of times to replay the current queues. 


Parameters None. 


Return Value nfResult is a short integer. 


StopSound ( }: nResult 


Purpose This function stops playing all voice queues, then flushes the 
contents of the queues. The sound driver for each voice is 
turned off. 


Parameters None. 


Return Value nResult is a short integer. 


WaitSoundState ( nState ) : nResult 


Purpose This function waits until the play driver enters the specified 
state. 


Parameters _nState is a short integer value specifying the state of the 
voice queues. It can be any one of the following: 
Value State 
S_ QUEUEEMPTY All voice queues are empty and 
sound drivers turned off 


S_ THRESHOLD A voice queue has reached 


threshold, returns voice 


S_ ALLTHRESHOLD All voices have reached thresh- 


old 
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Return Value nResult is a short integer value specifying the result of the 


function. It is zero if the function is successful. If the state 


is not valid, it is S_-SERDST. 


SyncAllVoices ( ): nResult 


Purpose 


Parameters 


This function queues a sync mark in each queue. Upon 

encountering a sync mark in a voice queue, the voice is 
turned off until sync marks are encountered in all other 
queues. This forces synchronization between all voices. 


None. 


Return Value nResult is a short integer value specifying the result of the 


function. It is zero if the function is successful. If a voice 


queue is full, nResult is S_SEROFUL. 


Count VoiceNotes ( nVoice ) : nNotes 


Purpose 


Parameters 


This function retrieves a count of the number of notes in the 
specified queue. Only those queue entries resulting from 
calls to Set VoiceNote are counted. 


nVoice is a short integer value specifying the voice queue to 
be counted. The first voice queue is numbered 1. 


Return Value nNotes is a short integer number specifying the number of 


notes in the given queue. 


GetThresholdEvent ( ): [pJnt 


Purpose 


Parameters 


This function retrieves a flag identifying a recent threshold 
event. A threshold event is any transition of a voice queue 
from nto n-1 where nis the threshold level in notes. 


None. 


Return Value IpInt is a long pointer to a short integer specifying a thresh- 


old event. 


GetThresholdStatus ( ) : fStatus 


Purpose 


This function retrieves the threshold event status for each 
voice. Each bit in the status represents a voice. If a bit is 
set, the voice queue level is currently below threshold. 


The GetThresholdStatus function also clears the thresh- 
old event flag. The threshold flag should be cleared only in 
this way. 
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Parameters None. 


Return Value fStatus is a short integer containing the status flags of the 
current threshold event. 


Set VoiceThreshold ( nVoice, nNotes ): nResult 


Purpose This function sets the threshold level for the given voice. 
When the number of notes remaining in the voice queue goes 
below nNotes the threshold flag is set. If the queue level is 
below nNotes when Set VoiceThreshold is called, the flag 
is not set. The Get ThresholdStatus function should be 
called to verify the current threshold status. 


Parameters nVotce is a short integer value specifying the voice queue to 
be set. 


nNotes is a short integer number specifying the number of 
notes in the threshold level. 


Return Value nfesult is a short integer value specifying the result of the 
function. It is zero if the function is successful. It is 1 if 
nNotes is out of range. 


4.12 Utility Functions 


This section describes useful functions and macros. 


HIBYTE ( ninteger ) : cHighByte 


Purpose This function retrieves the high-order byte from the integer 
value ninteger. 


Parameters _ninteger is a short integer value. 


Return Value cHtghByte, a byte integer value, is the ae order byte of the 
given value. 


LOBYTE ( ninteger ) : cLowByte 


Purpose This function extracts the low-order byte from the short 
integer value ninteger. 


Parameters _ninteger is a 16-bit integer value. 
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Return Value cLowByte, a byte integer value, is the low-order byte of the 


value. 


HIWORD ( lJnteger ) : wHighWord 


Purpose 


Parameters 


This function retrieves the high-order word from the long 
integer value l/nteger. 


lInteger is a long integer value. 


Return Value wHighWord, an unsigned short integer value, is the high- 


order word of the given long value. 


LOWORD ( l/nteger ) : whLowWord 


Purpose 


Parameters 


This function extracts the low-order word from the long 
value Unteger. 


lInteger is a long integer value. 


Return Value wlLowWord, an unsigned short integer value, is the low-order 


word of the long value. 


MAKELONG ( nLowWord, nHighWord ): dwinteger 


Purpose 


Parameters 


This function creates a unsigned long integer by concatenat- 
ing two integer values, nLowWord and nHtgh Word. 


nLowWord is a short integer value specifying the low-order 
word of the new long value. 


nHtgh Word is a short integer value specifying the high-order 
word of the new long value. 


Return Value dwlnteger is an unsigned long integer value. 


MAKEINTRESOURCE ( ninteger ) : IpString 


Purpose 


Parameters 


This function converts an integer value to a long pointer to 
a string (LPSTR type), with the high-order word of the 
long pointer set to zero. : 


ninteger is a short integer value. 


Return Value IpString is a long pointer to a string (LPSTR type). 
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MAKEPOINT ( Integer ) : Point 


Purpose 


Parameters 


Return Value 


This macro converts a long value containing the x and y 
coordinates of a point into a POINT structure. 


[Integer is a long value containing the x coordinate of the 
point in the low-order word and the y coordinate is in the 
high-order word. 


Potnt is a structure with POINT type containing the x and 
y coordinates. 


GetRValue ( rgbColor ): cRedValue 


Purpose 
Parameters 
Return Value 


This macro extracts the red value from an RGB color value. 
rgbColor is an RGB color value. 


clted Value is a byte containing the red value of rgbColor. 


GetGValue ( rgbColor ) : cGreenValue 


Purpose 


Parameters 
Return Value 


This macro extracts the green value from an RGB color 
value. 


rgobColor is an RGB color value. 


cGreenValue is a byte containing the green value of 


rgbColor. 


GetBValue ( rgbColor ) : cBlue Value 


Purpose 
Parameters 
Return Value 


min ( Valued, 


Purpose 
Parameters 
Return Value 
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This macro extracts the blue value from an RGB color value. 
rgbColor is an RGB color value. 


cBlue Value is a byte containing the blue value of rgbColor. 


Value2 ): MinValue 
This macro returns the minimum of Valuel and Value?. 
Valuei and Value2 are two arbitrary values to be compared. 


The return value is Valuel or Value2, whichever is lesser. 
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max ( Valuel, Value2 ): MaxValue 


Purpose 


Parameters 


This macro returns the maximum of Valuel and Value2. 


Valuel and Value2 are two arbitrary values to be compared. 


Return Value The return value is Valuel or Value2, whichever is greater. 


4.13 File I/O Functions 


This section describes functions used for creating and opening files. 


OpenFile ( [pF ileName, lpReOpenBuff, wStyle ) : hFile 


Purpose 


Parameters 


This function creates, opens, reopens, or deletes a file. 


lpFtleName is a long pointer to a null-terminated character 
string specifying the name of the file to be opened. The 
string must consist of characters from the ANSI character 
set. 


lpReOpenBuff is a long pointer to a data structure having 
OFSTRUCT type. The structure receives information 
about the file when the file is first opened, and is used in 
subsequent OpenfF'ile calls to refer to the open file. 


wStyle is an unsigned short integer value specifying the 
action to take. It can be combinations of the following: 


Value Meaning 

OF_ READ Opens the file for reading only. 

OF_ WRITE Opens the file for writing only. 

OF_ READWRITE Opens the file for reading and 
writing. 

OF_ CREATE Creates the file if it does not 
already exist. 

OF_ REOPEN Opens the file using informa- 
tion in the reopen buffer. 

OF_ EXIST Creates or opens the file, then 
closes it. Used to test for file 
existence. 
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OF_ PARSE Fills the OFSTRUCT structure 
but carries out no other action. 
OF_ PROMPT Displays a dialog box that 


prompts the user for permis- 
sion to create a file if the 
requested file does not exist. 


OF_ CANCEL Adds a Cancel button to the 
OF_ PROMPT dialog box. 
Pressing the Cancel button 
directs OpenF ile to return a 
file-not-found error. 


OF_ VERIFY Verifies that the date and time 
of the file are the same as when 
it was previously opened. Use- 
ful as an extra check for read- 
only files. 


OF_ DELETE Deletes the file. 


These styles can be combined using the logical OR operator. 


Return Value hF tle is an MS-DOS file handle if the function is successful. 


Notes 


Otherwise, AF le is -1. 
To close the file after use, use the MS-DOS system close call. 


GetTempFileName ( cDriveLetter, lpPrefizString, wUnique, lp Temp- 


Purpose 
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FileName ) : nUniqueNumber 


This function creates a temporary filename with the follow- 
ing form: 


drives\ path\ ~ prefizuuuu. TMP 


where drive is the drive letter specified by cDriveLetter, path 
is the pathname of the temporary file (either the root direc- 
tory of the specified drive or the directory specified in the 
TEMP environment variable), prefiz is all letters (up to the 
first inter) of the string pointed to by lpPrefixString, and 
uuuu is a hexadecimal representation of the number 
specified by wUnique. 


Parameters 


System Resource Functions 


cDriveLetter is a byte integer specifying the suggested drive 
for the temporary filename. If cDriveLetter is 0, the default 
drive is used. 


lpPrefizString is a long pointer to a null-terminated string to 
be used as the temporary filename prefix. 


wUnique is an unsigned short integer. 


lp Temp tleName is a long pointer to a buffer where the tem- 
porary filename is stored. 


Return Value nUntgueNumber, a short integer value, is the unique numeric 


Notes 


value used in the temporary filename. If a nonzero value 
was given for the wUnique parameter, nUniqueNumber is the 
same number. 


GetTempFileName uses the suggested drive letter for 
creating the temporary filename except in the following 
cases: 


1. Ifa hard disk is present, Get TempFileName 
always uses the drive letter of the first hard disk. 


2. Ifa TEMP environment variable is defined and its 
value begins with a drive letter, that drive letter is 
used. 


If the TF_ FORCEDRIVE bit of cDriveLetter is set, the 
above exceptions do not apply. The temporary filename will 
always be created in the current directory of the drive 
specified by cDriveLetter, regardless of the presence of a 
hard disk or the TEMP environment variable. 


If wUnique is zero, Get TempFileName attempts to form a 
unique number based on the current system time. If a file 
with the resulting filename already exists, the number is 
increased by one and the test for existence is repeated. This 
process continues until a unique filename is found; Get- 
TempFileName then creates a file by that name and closes 
it. 


No attempt is made to create and open the file when 
wUnique is nonzero. 
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GetTempDrive ( cDriveLetter ) : cOptDriveLetter 


Purpose This function takes a drive letter or zero and returns a letter 
specifying the optimal drive for a temporary file. The 
optimal drive is the disk drive that can provide the best 
access time during disk operations with a temporary file. 


The function returns the drive letter of a hard disk if the 
system has one. Otherwise, if cDriveLetter is zero, it returns 
the drive letter of the current disk, or if cDriveLetter is a 
letter, it returns the letter of that drive or one that exists. 


Parameters cDriveLetter is a byte integer value specifying a disk drive 
letter, for example, “A” for disk drive A. 


Return Value cOptDriveLetter is a byte integer value specifying the 
optimal disk drive for temporary files. 
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5.1 Introduction 


This chapter describes the data types and structures used by Windows 
functions. 


5.2 Data Types 


This section describes the data types used with Windows functions. The 
data types are keywords that define the size and meaning of the parameters 
and return values associated with the functions. 


Value Types 


Windows functions use the following character, integer, and Boolean types: 


Type Definition 

char Specifies an ASCII character, or a signed 8-bit integer. 

BYTE Specifies an unsigned 8-bit integer. 

int Specifies a signed 16-bit integer. 

short Specifies a signed 16-bit integer. 

WORD Specifies an unsigned 16-bit integer. 

long Specifies a signed 32-bit integer. 

LONG Specifies a signed 32-bit integer. 

DWORD Specifies an unsigned 32-bit integer, or a segment/offset 
address combination. 

BOOL Specifies a 16-bit Boolean value. 

VOID Specifies an empty value. It is used with a function to 


specify no return value. 
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Pointer Types 


The Windows functions use many pointer types. Most pointer type names 
begin with either a “P” prefix for a short pointer (1.e., data is within the 
current data segment), or “LP” for a long pointer (i.e., a 32-bit 
segment/offset pointer). The following is a list of common pointer types: 


Type 


PSTR 
PINT 
LPSTR 
LPINT 
LPRECT 
LPMSG 
FARPROC 
FAR 


NEAR 


Handles 


Definition 


Specifies a pointer to a character string. 

Specifies a pointer to a signed 16-bit integer. 
Specifies a long pointer to a character string. 
Specifies a long pointer to a signed 16-bit integer. 
Specifies a long pointer to a RECT data structure. 
Specifies a long pointer to a MSG data structure. 
Specifies a long pointer to a function. 


Specifies a data type attribute that can be used to create 
a long pointer. 


Specifies a data type attribute that can be used to create 
a short pointer. 


Windows uses a large variety of handles to refer to resources that have been 
loaded into memory and can be used by applications. Windows provides 
access to resources through internally maintained tables. The entries in the 
table define the locations and type of data available. The handle is an 


index to the table. 


The following is a list of common handles: 


Type 
HANDLE 


HSTR 
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Definition 


Specifies a general handle. It represents a 16- 
bit index to a table entry identifying program 
data. 


Specifies a handle to a string resource. It is a 
16-bit index to a resource table entry. 


HCURSOR 


HICON 


HMENU 


HDC 


HPEN 


HFONT 


HBRUSH 


HBITMAP 


HRGN 


GLOBALHANDLE 


LOCALHANDLE 
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Specifies a handle to a cursor resource. It is a 
16-bit index to a resource table entry. 


Specifies a handle to an icon resource. It is a 
16-bit index to a resource table entry. 


Specifies a handle to a menu resource. It is a 
16-bit index to a resource table entry. 


Specifies a handle to a display context. It is a 
16-bit index to GDI’s display context tables. 


Specifies a handle to a physical pen. It is a 
16-bit index to GDI’s physical drawing 
objects. 

Specifies a handle to a physical font. It is a 


16-bit index to GDI’s physical drawing 
objects. 


Specifies a handle to a physical brush. It is a 
16-bit index to GDI’s physical drawing 
objects. 


Specifies a handle to a physical bitmap. It is a 
16-bit index to GDI’s physical drawing 
objects. 


Specifies a handle to a physical region. It is a 
16-bit index to GDI’s physical drawing 
objects. 

Specifies a handle to global memory. It is a 


16-bit index to a block of memory allocated 
from the system’s global heap. 


Specifies a handle to local memory. It is a 16- 
bit index to a block of memory allocated from 
the application’s local heap. 
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5.3 Window Data Structures 


This section describes the data structures used for window class registra- 
tion, application queue messages, window messages, and window creation. 


WNDCLASS - Window Class Data Structure 
The WNDCLASS structure contains the following fields: 


WORD style 

FARPROC IpfnWndProc 
int cbClsExtra 
int cbWndExtra 
HANDLE hIinstance 
HICON hilcon 

HCURSOR hCursor 
HBRUSH hbrBackground 
LPSTR lpszMenuName 
LPSTR lpszClassName 


The WNDCLASS fields have the following meanings: 
Field Definition 


style Specifies the class style. It can be any combination of 
the following: 
CS_ VREDRAW Redraw entire window if vertical 
size changes. 
CS. HREDRAW — Redraw entire window if horizon- 
tal size changes. 
CS_ KEYCVTWINDOW 
Reserve space at bottom of screen 
for key conversion window. 


CS DBLCLKS Send double click messages to 
window. 


CS_OEMCHARS OFM character translation (not 
used by Windows applications). 
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Ipfn WndProe 


cbClsExtra 


cbWndExtra 


hInstance 


hCursor 


hIcon 
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CS. OWNDC Give each window instance its 
own display context. 

CS_ CLASSDC Give the window class its own 
display context (shared by 
instances). 

Note Although the CS_ OWNDC style 


is convenient, each display con- 
text occupies approximately 800 
bytes of memory, so it must be 
used with discretion. 


The above styles can be combined using the bitwise 
OR operator. 


Specifies the window function. It must be a long 
pointer to the function. 


Specifies the number of bytes to allocate after the 
window class structure. 


Specifies the number of bytes to allocate after the 
window instance. 


Specifies the class module. It must be an instance 
handle. It must not be NULL. 


Specifies the class cursor. It must be a handle to a 
cursor resource. If hCursoris NULL, the application 
must explicitly set the cursor shape whenever the 
mouse moves into the application’s window. 


Specifies the class icon. It must be a handle to an 
icon resource. If h/con is NULL, the application must 
draw an icon whenever the user closes the 
application’s window. 
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hbrBackground Specifies the class background brush. It can be either 


IpszMenuName 


lpszClassName 


a handle to the physical brush to be used for painting 
the background or a color value. If a color value is 
given, it must be one of the standard system colors 
listed below, and the value 1 must be added to the 
chosen color (for example, 

COLOR_ BACKGROUND-+ 1 specifies the system 
background color). If a color value is given, it must 


be converted to HBRUSH type. 


COLOR_ SCROLLBAR 
COLOR_ BACKGROUND 
COLOR_ ACTIVECAPTION 
COLOR_ INACTIVECAPTION 
COLOR MENU 

COLOR _ WINDOW 

COLOR_ WINDOWFRAME 
COLOR MENUTEXT 
COLOR_ WINDOWTEXT 
COLOR_ CAPTIONTEXT 


When hbrBackground is NULL, the application must 
paint its own background whenever it is requested to 
paint in its client area. The application can deter- 
mine when the background needs painting by han- 
dling the WM_ ERASEBKGND message or by testing 
the fErase field of the PAINTSTRUCT structure 
filled by BeginPaint. 


Specifies the resource name of the class menu (as the 
name appears in the resource file). It must be a long 
pointer to a null-terminated ASCII string. If an 
integer value is used to identify the menu, the 
MAKEINTRESOURCE macro can be used. If 
lpszMenuName is NULL, windows belonging to this 
class have no default menu. 


Specifies the name of the window class. It must be a 
long pointer to a null-terminated ASCII string. 
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MSG - Message Data Structure 


The MSG structure contains information from the Windows application 
queue. The structure has the following fields: 


HWND hwnd 

WORD message 
WORD wParam 
LONG lParam 


DWORD time 
POINT pt 


The MSG fields have the following meanings: 


Field Definition 

hwnd Specifies a handle to the window receiving the message. 

message Specifies the message number. 

wParam Specifies additional information about the message. The 
exact meaning depends on the message value. 

[Param Specifies additional information about the message. The 
exact meaning depends on the message value. 

time Specifies the time at which the message was posted. 

pt Specifies the position of the mouse (in screen coordinates) 


when the message was posted. 


PAINTSTRUCT - Windows Paint Information 


The PAINTSTRUCT structure contains information for an application 
that can be used to paint the client area of a window owned by the applica- 
tion. The structure has the following fields: 


HDC hdc 

BOOL fErase 
RECT rcPaint 
BOOL fRestore 
BOOL fIncUpdate 


BYTE rgbReserved[16] 


257 


Windows Reference Manual 


The PAINTSTRUCT fields have the following meanings: 


Field Definition 

hde Specifies the display context to be used for painting. 

fErase Specifies whether or not the background has been 
redrawn. It has been redrawn if nonzero. 

rcPaint Specifies the upper left and lower right corners of the 
rectangle in which the painting is requested. 

fRestore Used internally by Windows. 

fIncUpdate Used internally by Windows. 

rgbReserved Specifies a reserved block of memory used internally 


by Windows. 


CREATESTRUCT - Window Creation Structure 


The CREATESTRUCT structure defines the initialization parameters 
passed to an application’s window function with the WM_ CREATE and 
WM_ NCCREATE messages. The structure contains the following fields: 


LPSTR lpCreateParams 
HANDLE hInstance 
HANDLE hMenu 

HWND hwndParent 


int cy 
int ox 
THE 4 

Int x 
long style 


LPSTR lpszName 
LPSTR lpszClass 


The CREATESTRUCT fields have the following meanings: 
Field Definition 


IpCreateParams Specifies the window creation parameters. It can 
be a long pointer to data to be used when creating 
the window. 


hInstance Specifies the module instance handle of the module 
owning the new window. 


hMenu Specifies the handle of the menu to be used by the 
new window. 
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hwndParent 


cy 
cx 


style 


Ipsz Name 


IpszClass 
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Specifies the window handle of the window owning 
the new window. It is NULL if the new window is a 
top-level window. 


Specifies the height of the new window. 


Specifies the width column of the new window. It is 
used by child and popup windows only. 


Specifies the y coordinate of the upper left corner of 
the new window. Coordinates are relative to the 
parent window if the new window is a child. Other- 
wise, they are relative to the screen origin. 


Specifies the x coordinate of the upper left corner of 
the new window. Coordinates are relative to the 
parent window if the new window is a child. Other- 
wise, they are relative to the screen origin. 


Specifies the new window’s style. 


Specifies the new window’s name. It is a long 
pointer to a null-terminated ASCII string. 


Specifies the new window’s class name. It is a long 
pointer to a null-terminated ASCII string. 


5.4 GDI Data Structures 


This section describes the data structures used by the Graphics Device 
Interface (GDI) functions. 


LOGPEN =. Logical Pen Attribute Information 


The LOGPEN structure defines the style, width, and color of a pen. A 
pen is a drawing object used to draw lines and borders. The LOGPEN 
structure is used in the CreatePenIndirect function. 


The structure contains the following fields: 


WORD lopnstyle 
POINT lopnWidth 
DWORD lopnColor 
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The LOGPEN fields have the following meanings: 


Field Definition 

lopnStyle Specifies the pen type. It can be any one of the following: 
Solid — 
Dashed --- 
Dotted 


Dash-dotted a ; 
Dash-dot-dotted W_.._.. 
Null 


lopnWidth Specifies the pen width in logical units. If lopnWadth is 0, 
the pen is one pixel width on raster devices. 


Om GW Doe © 


lopnColor Specifies the pen color. It must be an RGB color value. 


LOGBRUSH .- Logical Brush Attribute Information 


The LOGBRUSH structure defines the style, color, and pattern of a physi- 
cal brush to be created using the CreateBrushIndirect function. The 
structure contains the following fields: 


WORD lbStyle 
DWORD lbColor 
short lbHatch 


The LOGBRUSH fields have the following meanings: 
Field Definition 


IbStyle Specifies the brush style. It can be any one of the following: 


BS_ SOLID 

BS_ HOLLOW 
BS_ HATCHED 
BS_ PATTERN 


IbColor Specifies the color in which the brush is to be drawn. It must 
be an RGB color value. If lbStyle is BS- HOLLOW or 
BS_ PATTERN, /bColor is ignored. 
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IbHatch Specifies a hatch style. The meaning depends on the brush 


style. 


If lbStyle is BS_ HATCHED, lbHatch specifies the orientation 
of the lines used to create the hatch. It can be any one of the 
following: 


HS_ HORIZONTAL - horizontal hatch 
HS_ VERTICAL - vertical hatch 
HS_ FDIAGONAL - 45-degree upward hatch from left to right 


HS_ BDIAGONAL - 45-degree downward hatch from left to right 


HS— CROSS - horizontal and vertical cross-hatch 
HS_ DIAGCROSS - 45-degree cross-hatch 


If lbStyle is BsS- PATTERN, /bHatch must be a handle to the 
bitmap defining the pattern. 


If (6Style is BS_ SOLID or BS_ HOLLOW, /bHatch is ignored. 


LOGFONT Logical Font Descriptor 
The LOGFONT structure defines the attributes of a font. A font is a 


drawing object used to write text on a display surface. The structure is 
used in the CreateFontIndirect function to direct GDI to select a match- 
ing physical font. The LOGFONT structure contains the following fields: 


short 
short 
short 
short 
short 
BYTE 
BY LE 
BY'TE 
BY LE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 


1 fHeight 

1 fWidth 

1 fEscapement 
1fOrientation 
l1fWeight 
tETtalic 

1fUnder line 
1fStrikeOut 
l1fCharSet 
1fOutPrecision 
l1fClipPrecision 
lfQuality 
1fPitchAndFamily 
1 fFaceName [LF_FACESIZE] 
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The LOGFONT fields have the following meanings: 


Field 
lfHeight 


IfWidth 


IfEscapement 


IfOrientation 


IfWeight 


IfItalic 
IfUnderline 
lfStrikeOut 
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Definition 


Specifies the height of the font in user units. The 
height of a font can be specified in three ways. If 
lfHeight is greater than zero, it is transformed into 
device units and matched against the cell height of 
the available fonts. If [fHeight is zero, a reasonable 
default size is used. If l[fHezght is less than zero, it 
is transformed into device units and the absolute 
value is matched against the character height of 
the available fonts. 


Specifies the average width of characters in the font 
in user units. If lfWtdth is zero, the aspect ratio of 
the device will be matched against the digitization 
aspect ratio of the available fonts looking for the 
closest match by absolute value of the difference. 


Specifies the angle in tenths of degrees between the 
escapement vector and the x-axis of the display sur- 
face. The escapement vector is the line through the 
origins of the first and last characters on a line. 
The angle is measured counterclockwise from the 
X-axis. 


Specifies the angle in tenths of degrees between the 
baseline of a character and the x-axis. The angle is 
measured counterclockwise from the x-axis. 


Specifies the font weight in inked pixels per 1000. 
Although it can be any integer value from 0 to 
1000, the common values are: 


400 normal 


700 bold 

These values are approximate; the actual appear- 
ance depends on the font face. If [fWetght is 0, a 
default weight is used. 


Indicates an italic font if set to nonzero. 
Indicates an underlined font if set to nonzero. 


Indicates a strikeout font if set to nonzero. 


lfCharSet 


IfOutPrecision 


IfClipPrecision 


IfQuality 
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Specifies the font’s character set. It can be any one 
of the following: 


ANSI CHARSEIT 
OlLM_ CHARSET 


The characters of the ANSI CHARSET set are 
defined in Appendix C. The OKM_CHARSET set 


is system-dependent. 


Specifies the font’s output precision. The output 
precision defines how closely the output must 
match the requested font’s height, width, character 
orientation, escapement, and pitch. Currently 


must be set to OUT_ DEFAULT_ PRECIS. 


Specifies the font’s clipping precision. The clipping 
precision defines how to clip characters that are 
partially outside the clipping region. Currently 
must be set to CLIP_ DEFAULT_ PRECIS. 


Specifies the font’s output quality. The output 
quality defines how carefully GDI must attempt to 
match the logical font attributes to those of an 
actual physical font. It can be any one of the fol- 
lowing: 


PROOF_ QUALITY 
The character quality of the font is more 
important than exact matching of the logical 
font attributes. For GDI fonts, scaling is dis- 
abled and the font closest in size is chosen. 
Although the chosen font size may not be 
mapped exactly when PROOF_ QUALITY is 
used, the quality of the font is high and there 
is no degradation of appearance. Bold, italic, 
underline, and strikeout are synthesized if 
needed. 


DRAFT_ QUALITY 
The appearance of the font is less important 
than when PROOF_ QUALITY is used. For 
GDI fonts, scaling is enabled, with the result 
that more font sizes are available, but the 
quality may be lower. Bold, italic, underline, 
and strikeout are synthesized if needed. 


DEFAULT_ QUALITY 


The appearance of the font does not matter. 
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IfPitchAndF amily 


IffaceName 


Specifies the font pitch and family. The two low- 
order bits specify the pitch of the font and can be 
any one of the following: 


DEFAULT _ PITCH 
FIXED_ PITCH 
VARIABLE_ PITCH 


The four high-order bits of the field specify the font 
family and can be any one of the following: 


FF_ DONTCARE 
rF_ ROMAN 

FF_ SWISS 

r'F_ MODERN 

FF_ SCRIPT 

FF_ DECORATIVE 


The constants are defined such that the proper 
value can be obtained by ORing together one pitch 
constant with one family constant. Font families 
describe the look of a font in a general way. They 
are intended for specifying fonts when the exact 
facename desired is not available. The families are: 


FF_ DONTCARE 


Don’t care or don’t know. 


FF_ ROMAN 
Fonts with variable stroke width, serifed. 
Times Roman, Century Schoolbook, etc. 


FF_SWISS 
Fonts with variable stroke width, sans- 
serifed. Helvetica, Swiss, etc. 


FF_ MODERN 
Fonts with constant stroke width, serifed 
or sans-serifed. Fixed-pitch fonts are 
usually modern. Pica, Elite, Courier, etc. 


FF_ SCRIPT 


Cursive, etc. 


FF_ DECORATIVE 
Old English, etc. 


Specifies the name of the font’s typeface. It must 
be a null-terminated ASCII character string. If 
lff’'aceName is NULL, GDI uses a default face. 


Data Types and Structures 


BITMAP - Bitmap Data Structure 
The BITMAP structure defines the height, width, color format, and bit 


values of a logical bitmap. This structure can be used to create a bitmap 
with the CreateBitmapIndirect function and can be filled in for a partic- 
ular bitmap by passing the bitmap handle to GetObject. 


The BITMAP structure contains the following fields: 


short bm'l'ype 
short bmWidth 


short bmHeight 


short bmWidthBytes 


BYTE bmP lanes 
BYE bmBitsPixel 


LPSTR bmBits 


The fields within the BITMAP structure have the following meanings: 


Field 


bmType 
bm Width 
bmHeight 


bm WidthBytes 


bmPlanes 
bmBitsPixel 


bmBits 


Definition 


Specifies the bitmap type. For logical bitmaps, this 
must be 0. 


Specifies the width of the bitmap in pixels. The 
width must be greater than 0. 


Specifies the height of the bitmap in raster lines. 
The height must be greater than 0. 


Specifies the number of bytes in each raster line. 
This must be an even number since GDI assumes 
that the bit values of a bitmap form an array of 
integer (2-byte) values. In other words, 6m Width- 
Bytes*8 must be the next multiple of eight greater 
than or equal to bmWidth. 


Specifies the number of color planes in the bitmap. 


Specifies the number of adjacent color bits on each 
plane needed to define a pixel. 


Specifies the location of the bit values for the bit- 
map. It must be a long pointer to an array of char- 
acter (1-byte) values. 
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POINT - Point Data Structure 


The POINT structure defines the x and y coordinates of a point. The 
structure contains the following fields: 


int x 
int y 


The fields have the following meanings: 


Field Definition 
x is the x coordinate value of a point. 
y is the y coordinate value of a point. 


RECT - Rectangle Data Structure 


The RECT structure defines the coordinates of the upper left and lower 
right corners of a rectangle. The structure contains the following fields: 


int left 
Lrit top 
int right 
int bottom 


The fields have the following meanings: 


Field Definition 

left Specifies the x coordinate of the upper left corner of a 
rectangle. 

top Specifies the y coordinate of the upper left corner of a 
rectangle. 

right Specifies the x coordinate of the lower right corner of a 
rectangle. 

bottom Specifies the y coordinate of the lower right corner of a 
rectangle. 


The width of the rectangle defined by the RECT structure must not exceed 
32K units. 
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RGB - Logical Color Specification 


A RGB color value is a long integer containing a red, a green, and a blue 
color field, each specifying the intensity of the given color. Intensities range 
from 0 to 255. The values are packed in the three low-order bytes of the 
long integer in the following format: r+ 28g + 21!®%4:b. 


OFF (hexadecimal) is the maximum value for a single byte, and 0 is the 
minimum. Black (that is, no color information) corresponds to 0, 0, 0 (0 in 
all three bytes). White is all color: FF, FF, FF. Gray is half energy, 
corresponding to 7F, 7F, 7F. Solid green would be 00, FF, 00. 


TEXTMETRIC - Basic Font Metrics 


The TEXTMETRIC structure is a list of the basic metrics of a physical 
font. The structure is returned by the Get TextMetrics function. 


The TEXTMETRIC structure contains the following fields: 


short tmHeight 

short tmAscent 

short tmDescent 

short tmInternalLeading 
short tmExternalLeading 
short tmAveCharWidth 
short tmMaxCharWidth 
short tmWeight 

BYTE tmItalic 

BYTE tmUnder lined 

BYTE tmStruckOut 

BYTE tmF irstChar 

BYTE tmLastChar 

BYTE tmDefaultChar 

BYTE tmBreakChar 

BYTE tmPitchAndk amily 
BYTE tmCharSet 

short tmOverhang 

short tmDigitizedAspectX 
short tmDigitizedAspectyY 
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The TEXTMETRIC fields are described below. All sizes are given in logi- 
cal = (i.e., they depend on the current mapping mode of the display con- 
text). 


Field Definition 

tmHeight Specifies the height of characters (Ascent + 
Descent). 

tmAscent Specifies the ascent of characters (units above 
the baseline). 

tmDescent Specifies the descent of characters (units 
below the baseline). 

tmInternalLeading Specifies the amount of leading inside the 
bounds set by tmHezght. Accent marks may 
occur in this area. This may be zero at the 
designer’s option. 

tmExternalLeading Specifies the amount of extra leading that the 
designer requests the application add between 
rows. Since this area is outside the font, it 
contains no marks, and will not be altered by 
text output calls in either OPAQUE or 
TRANSPARENT mode. This may be zero at 
the designer’s option. 

tmAveChar Width Specifies the average width of characters in 
the font (loosely defined as the width of the 
letter ‘X’). 

tmMaxChar Width Specifies the maximum width of any character 
in the font. 

tm Weight Specifies the weight of the font. 

tmltalic Specifies an italic font if it is nonzero. 

tmUnderlined Specifies an underlined font.if it is nonzero. 

tmStruckOut Specifies an struckout font if it is nonzero. 

tmF irstChar Specifies the value of the first character 
defined in the font. 

tmLastChar Specifies the value of the last character 
defined in the font. 

tmDefaultChar Specifies the value of the character that will 


be substituted for characters that are not in 
the font. 


tmBreakChar 


tmPitchAndFamily 


tmCharSet 
tmOverhang 


Data Types and Structures 


Specifies the value of the character that will 
be used to define word breaks for text 
justification. 


Specifies the pitch and family of the selected 
font. The low-order bit is set if the font is 
variable pitch. The four high-order bits give 
the family of the font. tmPitchAndF amily can 
be combined with the hexadecimal value FO, 
using the bitwise AND operator, and then 
directly compared for equality with the font 
family names. Refer to the LOGFONT 


structure for a description of the font families. 
Specifies the character set of the font. 


Specifies the per string extra width that may 
be added to some synthesized fonts. When 
synthesizing some attributes, such as bold or 
italic, GDI or a device may have to add width 
to a string on both a per character and per 
string basis. For example, GDI emboldens a 
string by expanding the intracharacter spac- 
ing and overstriking with an offset, and italli- 
cizes a font by skewing the string. In either 
case there is an overhang past the basic string. 
For bold strings, it is the distance by which 
the overstrike is offset. For italic strings, it is 
the amount the top of the font is skewed past 
the bottom of the font. 


tmOverhang allows the application to deter- 
mine how much of the character width 
returned by a Get TextExtent call on a sin- 
gle character is the actual character width and 
how much is the per-string extra width. The 
actual width is the extent minus the overhang. 


tmDigitizedAspectX, tmDigitizedAspect Y 


Specify the aspect ratio of the device for which 
this font was designed. The ratio of tmDugit- 
wedAspectY to tmDigitizedAspectX can be 
compared to the ratio of Aspect Y to AspectX 
retrieved from GetDeviceCaps. 
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Drawing Modes 


Drawing modes define how GDI combines source and destination colors 
when drawing with the current pen. The drawing modes are actually 
binary raster operation codes, representing all possible Boolean functions of 
two variables, using the binary operations AND, OR, and XOR (exclusive 
OR) and the unary operation NOT. The table below lists the drawing 
modes and the Boolean operations they represent. Drawing modes are used 
in the SetROP2 function. 


Drawing Mode Functions of Dest and Pen 


R2_ BLACK 1 f* 9 Kf 
R2_NOTMERGEPEN 2 f* DPoen */ 
R2_MASKNOTPEN 3 /* DPRe */ 
R2_NOTCOPYPEN 4 /* Pn + 
R2_MASKPENNOT 5 f* PDna */ 
R2_NOT 6 /* Dn a / 
R2_XORPEN 7 f= Pe yr 
R2_NOTMASKPEN 8 /* DPan */ 
R2_MASKPEN ~, ee DP a me 
R2_NOTXORPEN 10 **® DP F/ 
R2_NOP 11 ye DD wf 
R2_MERGENOTPEN 12 /* DPro */ 
R2_COPYPEN 13 yt Ff mi 
R2_MERGEPENNOT 14 f* PDs */ 
R2_MERGEPEN 15 /* DPo 9 
R2_WHITE 16 ¢*® |] wif 


Raster Operation Codes 


Raster operation codes (Rops) define how GDI combines colors in output 
operations that involve a current brush, a possible source bitmap, and a 
destination bitmap. The codes are actually tertiary raster operation codes, 
representing all possible Boolean functions of three variables, using the 
a ee AND, OR, and XOR (exclusive OR) and the unary opera- 
tion ; 
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The table below lists some of the codes and the Boolean operations they 


represent. 


SRCCOPY 
SRCPAINT 
ORCAND 
SRCINVERT 
SRCERASE 
NOTSRCCOPY 


NOTSRCERASE 


MERGECOPY 
MERGEPAINT 
PATCOPY 
PATPAINT 
PATINVERT 
DSTINVERT 
BLACKNESS 
WHITENESS 


OxOOCCOO20 /*dest=source 

OxOOEEOO86 /*dest=source OR dest 

OxOO8800C6 /*dest=source AND dest 
OxO0660046 /*dest= source XOR dest 
Ox00440328 /*dest= source AND (not dest ) 
Ox00330008 /*dest= (not source) 

OxOO1LIOOA6 /*dest= (not source) AND (not dest) 
OxOOCOOOCA /*dest= (source AND pattern) 
OxOOBBO226 /*dest= (source AND pattern) OR dest 
OxOOFOO0O021 /*dest= pattern 

OxOOFBOAO9 /*DPSnoo 

OxOOSA0049 =/*dest= pattern XOR dest 
OxO0550009 /*dest= (not dest) 

OxO0000042 /*dest= BLACK 

OxOOFFOO62 /*dest= WHITE 


A complete list of the functions is given in Appendix A. 


METAFILEPICT - Metafile Picture Structure 


The METAFILEPICT structure defines the metafile picture format used 
for exchanging metafile data through the clipboard. The structure contains 
the following fields: 


The fields of the METAFILEPICT structure have the following mean- 


int mm 
int XEXE 
int yExt 
HANDLE hMEF 
ings: 

Field 

mm 

xExt, yExt 


Definition 


Gives the mapping mode in which the picture is drawn. 


Gives the size of the metafile picture for all modes except 


MM_ ISOTROPIC and MM_ ANISOTROPIC. The x and 


y extents specify the rectangle within which the picture 


drawn. The coordinates are in units that correspond to 


the mapping mode. 


is 


For MM_ ISOTROPIC and MM_ ANISOTROPIC modes, 


which are scalable, xExt and yExt contain an optional 
“suggested size” in MM_HIMETRIC units. For 

MM_ ANISOTROPIC pictures, z//zt and ylzt can be 0 
when no suggested size is supplied. For 


MM_ ISOTROPIC pictures, an aspect ratio must be 
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mHF 


supplied even when no suggested size is given. (If a sug- 
gested size is given, the aspect ratio is implied by the 
size.) To give an aspect ratio without implying a sug- 
gested size, set zEzt and yEzt to negative values whose 
ratio is the appropriate aspect ratio. The magnitude of 
the negative zHzt and y&zt values will be ignored; only 
the ratio will be used. 


Handle to a memory metafile. 


5.5 Communication Data Structures 


This section describes the data structures used with the communication 
functions. 


DCB - Communications Device Control Block 


The DCB structure defines the control setting for the serial communica- 
tions device. The structure contains the following fields: 


BYTE 
WORD 
BYTE 
BYTE 
BYTE 
WORD 
WORD 
WORD 


BYTE 
BYTE 
BYE 
BYTE 
BYTE 
BYTE 
BYTE 
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Id 
BaudRate 
ByteSize 
Parity 
StopBits 
RlsTimeout 
CtsTimeout 
DsrTimeout 


fBinary: 1 
fRtsDisable: 1 
Parity: J 
fOutxCtsF low: 1 
fOutxDsrF low:1 
fDummy: 2 
fDtrDisable:1 


Data Types and Structures 


oh a Bie LOUK! 1 
BYTE Linx? 7 
BYTE fPeChar: 1 
BYTE fNull: 1 
BYTE fChEvt: 1 
BY TE fbDtrflow: 1 
BYTE fRtsflow: 1 
BYIL fDummy2: 1 
char XonChar 


char XoffChar 
WORD XonLim 

WORD XoffLim 
char PeChar 

char EofChar 
char EvtChar 
WORD TxDelay 


The DCB fields have the following meanings: 
Field Definition 


Id Identifies the communication device. This value is set by 
the device driver. If the most significant bit is set, then 
the DCB is for a parallel device. 


BaudRate Specifies the baud rate at which the communication 
device is to operate. 


ByteSize Specifies the number of bits in the characters to be 
transmitted and received. It can be any number in the 
range 4 to 8. 


Parity Specifies the parity scheme to be used. It can be any one 
of the following: 


NOPARITY - No parity 
ODDPARITY - Odd 
EVENPARITY - Even 
MARKPARITY - Mark 
SPACEPARITY - Space 


StopBits Specifies the number of stop bits to be used. It can be 
any one of the following: 


ONESTOPBIT - 1 stop bit 
ONESSTOPBITS - 1.5 stop bits 
TWOSTOPBITS - 2 stop bits 
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Rls Timeout 


CtsTimeout 


Dsr Timeout 


fBinary 


{RtsDisable 


fParity 


fOutxCtsFlow 


fOutxDsrF low 


fDtrDisable 


fOutxX 


fInX 
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Specifies the maximum amount of time, in milliseconds, 
the device should wait for the Receive Line Signal Detect 
signal (RLSD) to become high. (RLSD is also known as 
the Carrier Detect (CD) signal.) 


Specifies the maximum amount of time, in milliseconds, 
the device should wait for the Clear To Send signal (CTS) 
to become high. 


Specifies the maximum amount of time, in milliseconds, 
the device should wait for the Data Set Ready signal 
(DSR) to become high. 


Indicates binary mode. In nonbinary mode, HKofChar is 
recognized on input and remembered as the end of data. 


Indicates whether or not the Request To Send signal 
(RTS) is disabled. If set, RTS is not used and remains 
low. If clear, RTS is asserted when the device is opened, 
and dropped when closed. 


Indicates whether or not parity checking is enabled. If 
set, parity checking is performed and errors are reported. 


Indicates that Clear To Send ted is to be monitored for 
output flow control. If set and CTS drops, output is 
suspended until CTS is again asserted. 


Indicates that Data Set Ready (DSR) is to be monitored 
for output flow control, If set and DSR drops, output is 
suspended until DSR is again asserted. 


Indicates whether or not the Data Terminal Ready signal 
‘ag is disabled. If set, DTR is not used and remains 
low. If clear, DTR is asserted when the device is opened, 
and dropped when closed. 


Indicates that XON/XOFF flow control is to be used dur- 
ing transmission. If set, transmission stops when the 
XoffChar character is received, and starts again when the 
XonChar character is received. 


Indicates that XON/XOFF flow control is to be used dur- 
ing reception. If set, the XonChar character is sent when 
the receive queue comes within XoffLim characters of 
being full, and the XonChar character is sent when the 
receive queue comes within XonLim characters of being 
empty. 


fPeChar 


fNull 


fChEvt 


{[DtrF low 


fRtsFlow 


XonChar 


XoffChar 


XonLim 


XoffLim 


PeChar 
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Indicates that characters received with parity errors are 
to be replaced with the character specified by PeChar. 
{Parity must be set for the replacement to occur. 


Indicates that received NULL characters are to be dis- 
carded. 


Indicates that reception of the HutChar is to be flagged as 
an event. 


Indicates that the Data Terminal Ready (DTR) signal is 
to be used for receive flow control. If set, DTR is dropped 
when the receive queue comes within XoffLim characters 
of being full, and asserted when the receive queue comes 
within XonLim characters of being empty. 


Indicates that the Ready To Send (RTS) signal is to be 
used for receive flow control. If set, RTS is dropped when 
the receive queue comes within XoffLim characters of 
being full, and asserted when the receive queue comes 
within XonLim characters of being empty. 


Specifies the ASCII value of the XON character for both 
transmission and reception. 


Specifies the ASCII value of the XOFF character for both 


transmission and reception. 


Specifies the minimum number of characters allowed in 
the receive queue before the XON character is sent. 


Specifies the margin for the maximum number of charac- 
ters allowed in the receive queue before the XOFF charac- 
ter is sent. The XoffLim value is subtracted from the size 
of the receive queue (in bytes) to calculate the maximum 
number of characters allowed. 


Specifies the ASCII value of the character used to replace 
characters received with a parity error. 
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EvtChar Specifies the ASCII value of the character used to signal 
an event. 

EofChar Specifies the ASCII value of the character used to signal 
the end of data. 

TxDelay Specifies the minimum amount of time that must pass 


between transmission of characters. 


COMSTAT —- Communication Device Status 


The COMSTAT structure contains information about a communications 
device. The structure contains the following fields: 


BYTE fCtsHola: 1 

BYTE fDsrHold: 1 

BYTE fRisdHold: 1 
BYTE fASOLTHolas: 1 
BY'TE fXoffSent: 1 
BYTE reoLi 

BYTE fixims 1 


WORD cbInQue 
WORD cbOutQue 


The COMSTAT fields have the following meanings: 


Field Definition 

fCtsHold Indicates whether or not transmission is waiting for the 
Clear To Send (CTS) signal to be asserted. 

fDsrHold Indicates whether or not transmission is waiting for the 
Data Set Ready (DSR) signal to be asserted. 

fRisdHold Indicates whether or not transmission is waiting for the 
Receive Line Signal Detect (RLSD) signal to be asserted. 

fXoffHold Indicates whether or not transmission is waiting as a result 
of the XoffChar being received. 

fXoffSent Indicates whether or not transmission is waiting as a result 


of the XoffChar being transmitted. Transmission halts 
when the XoffChar is transmitted to facilitate systems that 
take the next character as XON, regardless of the actual 
character. 
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fEof 
{Txim 


cbInQue 
cbOutQue 
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Indicates whether or not the HofChar has been received. 


Indicates whether or not a character is waiting to be 
transmitted “immediately.” 


Specifies the number of characters in the receive queue. 


Specifies the number of characters in the transmit queue. 


5.6 Open File Structure 


OFSTRUCT - Open File Structure 
The OFSTRUCT structure contains the following fields: 


BYTE cBytes 

BYTE fF ixedDisk 
WORD nErrCode 

BY'TE reserved [4] 
BYTE szPathName [128] 


The fields have the following meaning: 


Field 


cBytes 
fFixedDisk 


nErrCode 


reserved 
szPathName 


Definition 


Length of OFSTRUCT structure in bytes. 


One byte specifying whether or not the file is on a fixed disk. 
It is nonzero if located on a fixed disk. 


An unsigned short integer specifying the DOS error code if 
OpenFile failed (i.e., returns —1). 


Four bytes reserved for future use. 


128 bytes containing the pathname of the file. 
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6.1 Introduction 


This chapter describes the file formats of the ASCII text files used to create 
and execute a Windows application. There are the following file types: 


Resource Script File 
Module Definition File 


Windows Initialization File 


The following sections describe each type in detail. 


6.2 Resource Script File 


The resource script file defines the names and attributes of the resources to 
be added to the application’s executable file. The file consists of one or 
more “resource statements” that define the resource type and original file. 
The following is a list of the resource statements: 


Single-line statements CURSOR 
ICON 
BITMAP 
FONT 


User-defined resources 


Multiple-line statements STRINGTABLE 
ACCELERATORS 
MENU 
DIALOG 


Directives # include 


# else 
# endif 


The following sections describe these statements in detail. 
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6.2.1 Single Line Statements 


The single line statements define resources that are contained in a single 
file, such as cursors, icons, and fonts. The statements associate the 
filename of the resource with an identifying name or number. The resource 
is added to the executable file when the application is created, and can be 
extracted during execution by referring to the name or number. 


The general form for all single line statements is: 

namelD resource-type |load-option|] |mem-option|] filename 

namelD is either a unique name or an integer number identifying the 
resource. For a FONT resource, the name/D must be a number; it cannot 


be a name. 


resource-type is one of the following keywords, specifying the type of 
resource to be loaded: 


Keyword Resource Type 

CURSOR A cursor resource is a bitmap defining the 
shape of the mouse cursor on the display 
screen. 

ICON An icon resource is a bitmap defining the 
shape of the icon to be used for a given appli- 
cation. 

BITMAP A bitmap resource is a custom bitmap that an 


application intends to use in its screen display 
or as an item In a menu. 


FONT A font resource is simply a file containing a 
font. The format of a font file is defined in 
Appendix C. 


load-option is an optional keyword specifying when the resource is to be 
loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately 
LOADONCALL Resource is loaded when called 


The default is LOADONCALL. 
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The mem-optton consists of the following keyword or keywords, specifying 
whether the resource is fixed or moveable and whether it is discardable: 


FIXED Resource remains at a fixed memory location 

MOVEABLE Resource can be moved if necessary to com- 
pact memory 

DISCARDABLE Resource can be discarded if no longer needed 


The default is MOVEABLE and DISCARDABLE for CURSOR, ICON, 
and FONT resources. The default for BITMAP resources is MOVE- 


ABLE. 


filename is an ASCII string specifying the MS-DOS filename of the file con- 
taining the resource. A full pathname must be given if the file is not in the 
current working directory. 


Examples 

pointer CURSOR point.cur 

pointer CURSOR DISCARDABLE point.cur 
10 CURSOR custom.cur 

desk ICON desk.ico 

desk ICON DISCARDABLE desk.ico 

Ld. ICON custom.ico 

disk BITMAP disk.bmp 

disk BITMAP DISCARDABLE disk.bmp 
12 BITMAP custom.bmp 


5 FONT CMROMAN.FON 


6.2.2 User-Defined Resources 

An application can also define its own resource. The resource can be any 
data that the application intends to use. A user-defined resource statement 
has the form: 


namelD typelD {load-option| [mem-option| filename 


namelD is either a unique name or an integer number identifying the 
resource. 
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typelD is either a unique name or an integer number identifying the 
resource type. If a number is given, it must be greater than 255. The type 
numbers 1 through 255 are reserved for existing and future predefined 
resource types. 


load-option is an optional keyword specifying when the resource is to be 
loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately 
LOADONCALL Resource is loaded when called 


The default is LOADONCALL. 


mem-option consists of the following keyword or keywords, specifying 
whether the resource is fixed or moveable and whether it is discardable: 


FIXED Resource remains at a fixed memory location 
MOVEABLE Resource can be moved if necessary to compact memory 
DISCARDABLE Resource can be discarded if no longer needed 


The default is MOVEABLE. 


filename is an ASCII string specifying the MS-DOS filename of the file con- 
taining the cursor bitmap. A full pathname must be given if the file is not 
in the current working directory. 


Example 


array MYRES data.res 
14 300 custom.res 


6.2.3 STRINGTABLE Statement 


The STRINGTABLE statement defines one or more more string 
resources for an application. String resources are simply null-terminated 
ASCII strings that can be loaded when needed from the executable file, 
using the LoadString function. 
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The STRINGTABLE statement has the form: 
STRINGTABLE |load-option| |mem-option| 
BEGIN 


string- definitions 


END 


where string-defintttons are one or more ASCII strings, enclosed in double 
quotation marks and preceded by an identifier. The identifier must be an 
integer. 


load-optton is an optional keyword specifying when the resource is to be 
loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately 
LOADONCALL Resource is loaded when called 


The default is LOADONCALL. 


The optional mem-optton consists of the following keyword or keywords, 
specifying whether the resource is fixed or moveable and whether it is dis- 
cardable: 


FIXED — Resource remains at a fixed memory location 
MOVEABLE Resource can be moved if necessary to compact memory 


DISCARDABLE Resource can be discarded if no longer needed 
The default is MOVEABLE and DISCARDABLE. 


Example 


#define IDS_HELLO 1 
#define IDS_GOODBYE 2 


STRINGTABLE 
BEGIN 
IDS_HELLO, "Hello" 
IDS_GOODBYE, "Goodbye" 
END 
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6.2.4 ACCELERATORS Statement 
The ACCELERATORS statement defines one or more accelerators for an 


application. An accelerator is a keystroke defined by the application to give 
the user a quick way to perform a task. The TranslateAccelerator func- 
tion is used to translate accelerator messages from the application queue 


into WM_ COMMAND or WM_SYSCOMMAND messages. 
The ACCELERATORS statement has the form: 
acctablename ACCELERATORS 


BEGIN 
event, idvalue [, type] |, NOINVERT] |, SHIFT] |, CONTROL] 


END 

acctablename is the name of the accelerator table. 

event is the keystroke to be used as an accelerator. It can be any one of the 
following: 


Character Meaning 


“char” A single character enclosed in double 
quotes. The character can be preceded 
by a caret (*), meaning that the charac- 
ter is a control character. 


ASCII character An integer value representing an ASCII 
character. The type must be ASCII. 
Virtual key character An integer value representing a virtual 


key. The type field must be VIRTKEY. 
tdvalue is an integer value identifying the accelerator. 


The type field is required only when event is an ASCII character or virtual 
key character. type is either ASCII or VIRTKEY; the integer value of event 
is interpreted accordingly. 


The NOINVERT flag, if given, means that no top-level menu item is 
highlighted when the accelerator is used. This is useful, for example, when 
defining accelerators for actions such as scrolling that do not correspond to 
a menu item. If NOINVERT is omitted, a top-level menu item will be 
highlighted (if possible) when the accelerator is used. 
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The SHIFT flag, if given, causes the accelerator to be activated only if the 
shift key is down. 


The CONTROL flag, if given, defines the character as a control character 
(the accelerator is only activated if the control key is down). This has the 
same effect as using a caret (”) before the accelerator character in the event 


field. 
Examples 


MainAcc ACCELERATORS 


BEGIN 
"-S" ID SAVE, NOINVERT 
VK_UP, 6, VIRTKEY, NOINVERT 
7, ID_BELL, ASCII 
"-o" ID BELL 
"G", ID_BELL, CONTROL 

END 


Note that the last three definitions are equivalent. 


6.2.5 MENU Statement 


The MENU statement defines the contents of a menu resource. A menu 
resource is a collection of information that defines the appearance and func- 
tion of an application menu. A menu is a special input tool that lets a user 
select commands from a list of command names. 


The MENU statement has the form: 
menulD MENU |load-optton| {mem-option| 
BEGIN 
ttem-definitions 
END 
menulD is a name or number used to identify the menu resource. 


load-option is an optional keyword specifying when the resource is to be 
loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately 
LOADONCALL Resource is loaded when called 


The default is LOADONCALL. 
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The optional mem-optton consists of the following keyword or keywords, 
specifying whether the resource is fixed or moveable and whether it is dis- 
cardable: 


FIXED Resource remains at a fixed memory location 
MOVEABLE Resource can be moved if necessary to compact memory 
DISCARDABLE Resource can be discarded if no longer needed 


ttem-definittons are special resource statements that define the items in the 
menu. 
Example 


The following is an example of a complete MENU statement. 


sample MENU 


BEGIN 
MENUITEM "Alpha", 100 
POPUP "Beta" 
BEGIN 
MENUITEM "Item 1", 200 
MENUITEM "Item 2", 201, CHECKED 
END 
END 


Item Definition Statements 


The MENUITEM and POPUP statements are used in the ttem-definttion 
section of a MENU statement to define the names and attributes of the 
actual menu items. Any number of statements can be given; each defines a 
unique item. The order of the statements define the order of the menu 
items. 


Note 


The MENUITEM and POPUP statements can only be used within 
an ttem-definttion section of a MENU statement. 
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MENUITEM text, result, optionlist 


Purpose 


Parameters 


Examples 


This optional statement defines a menu item. 


text is an ASCII string, enclosed in double quotation marks, 
specifying the name of the menu item. The string can con- 
tain the escape characters \t and \a. The \t character 
inserts a tab in the string when displayed and is used to 
align text in columns. Tab characters should be used only 
in popup menus, not in menu bars. The \a character right- 
justifies all text that follows it. To insert a double quote 
character (") in the text, use two double quote characters 


result is an integer number specifying the result generated 
when the user selects the menu item. Menu item results are 
always integers and are sent to the window owning the 
menu when the user clicks on the menu item name. 


optioniist is one or more predefined menu options, separated 
by commas or spaces, that specify the appearance of the 
menu item. The menu options are as follows: 


Option Meaning 

MENUBREAK _ Item is immediately preceded by a new 
line. 

CHECKED Item has a checkmark next to it. 

INACTIVE Item name is displayed, but cannot be 
selected. 

GRAYED Item name is initially inactive and 


drawn with a gray highlight. 


The INACTIVE and GRAYED options cannot be used 
together. 


MENUITEM "Alpha", 1, CHECKED, GRAYED 
MENUITEM "Beta", 2 
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POPUP text, optioniist 


Purpose 


Parameters 
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This statement marks the beginning of a popup menu 
definition. A popup menu is a special menu item that 
displays a sublist of menu items when it is selected. The 
POPUP statement actually has the form: 


POPUP tezt, optionlist 
BEGIN 
ttem- definitions 


END 


where ttem-definittons can be any number of MENUITEM 
statements. POPUP statements in a popup menu are not 
allowed. 


text is an ASCII string, enclosed in double quotation marks, 
specifying the name of the popup. 


optionitst is one or more predefined menu options that 
specify the appearance of the menu item. It can be any one 
of the following: 


Option Meaning 


MENUBREAK Item is placed in a new column. 
MENUBARBREAK __ Item is placed in a new column. 


The old and new columns are 
separated with a bar. 


CHECKED Item has a checkmark next to it. 

INACTIVE Item name is displayed, but can- 
not be selected. 

GRAYED Item name is initially inactive 


and drawn with a gray highlight. 


The options can be combined using the bitwise OR operator. 
The INACTIVE and GRAYED options cannot be used 
together. 


File Formats 


Example 
chem MENU 
BEGIN 
POPUP "Elements" 
BEGIN 
MENUITEM "Oxygen", 200 
MENUITEM "Carbon", 201, CHECKED 
MENUITEM "Hydrogen", 202 
END 
POPUP "Compounds", CHECKED 
BEGIN 
MENUITEM "Glucose", 301 
MENUITEM "Sucrose", 302, CHECKED 
MENUITEM "Lactose", 303, MENUBREAK 
MENUITEM "Fructose", 304 
END 
END 
MENUITEM SEPARATOR 
Purpose This special form of the MENUITEM statement creates an 
inactive menu item that serves as a dividing bar between 
two active menu items. In popup menus, the bar is horizon- 
tal. In a regular menu, the bar is vertical. 
Parameters None. 
Example 


MENUITEM "Roman", 206 
MENUITEM SEPARATOR 
MENUITEM "20 Point", 301 
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6.2.6 DIALOG Statement 


The DIALOG statement defines a template that can be used by an appli- 
cation to create dialog boxes. 


The dialog statement has the form: 


dtalogname DIALOG |load-option| [mem-option| xz, y, width, height 
option-statements 


BEGIN 


control-statements 


END 


The parts of the DIALOG statement are described below. 


The name DIALOG can also be used as the class name parameter to the 
Create Window function to create a window with dialog box attributes. 


namelD DIALOG |load-option| |mem-option] 2, y, width, height 


Purpose 


Parameters 
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This statement marks the beginning of a DIALOG state- 
ment. It defines the name of the dialog box, memory and 
load options, the box’s starting location on the display 
screen, its width, and its height. 


namelD is either a unique name or an integer number identi- 
fying the resource. 


load-opttion is an optional keyword specifying when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately 
LOADONCALL Resource is loaded when called 


The default is LOADONCALL. 


The optional mem-option consists of the following keyword 
or keywords, specifying whether the resource is fixed or 
moveable and whether it is discardable: 


FIXED Resource remains at a fixed memory 
location 
MOVEABLE Resource can be moved if necessary 


to compact memory 


DISCARDABLE Resource can be discarded if no 


longer needed 
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The default is MOVEABLE. 


zand y are integer numbers specifying the x and y coordi- 
nates on the display screen of the upper left corner of the 
dialog box. The exact meaning of the coordinates depends 
on the style defined by the STYLE statement. For child 
style dialog boxes, the coordinates are relative to the origin 
of the parent window. For popup style boxes, the coordi- 
nates are relative to the origin of the display screen. 


width and hetght are integer numbers specifying the width 
and height of the box. The width units are 1/4 the width of 
a character; the height units are 1/8 the height of a charac- 
ter. 


Example 


errmess DIALOG 10, 10, 300, 200 
The following is a complete example of a DIALOG statement. 


#include "windows.h" 


errmess DIALOG 10, 10, 300, 110 
STYLE WS_POPUP |WS_BORDER 
CAPTION "Error!" 


BEGIN 
CTEXT "Select One:", 1, 10, 10, 280, 12 
RADIOBUTTON "Retry", 2, 75, 30, 60, 12 
RADIOBUTTON "Abort", 3, 75, 50, 60, 12 
RADIOBUTTON "Ignore", 4, 75, 80, 60, 12 
END 


Dialog Option Statements 


The dialog option statements define special attributes of the dialog box, 
such as its style, caption, and menu. The option statements are optional. 
If not given, the dialog box is given a default attribute. 


STYLE style 


Purpose This optional statement defines the window style of the dia- 
log box. The window style specifies whether the box is a 
popup or a child window. 
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The default style has the following attributes: 


WS_ POPUP 
Ws_ BORDER 
WS_SYSMENU 


Parameters style is an integer value or predefined name specifying the 
window style. It can be any of the window styles defined for 
the Create Window function (see Chapter 2, “Window 
Functions” ). 


The style DS_SYSMODAL can also be used to create a sys- 
tem modal dialog box. 


Notes If the predefined names are used, the # include directive 
must be used to include the “WINDOWS.H_” file in the 
resource script. 


CAPTION captiontezt 


Purpose This optional statement defines the dialog box’s title. The 
title appears in the box’s caption bar (if it has one). 


The default caption is empty. 


Parameters _captiontert is a ASCII character string enclosed in double 
quotation marks. 


Example 
CAPTIGN “Errort” 
MENU menuname 
Purpose This optional statement defines the dialog box’s menu. 


The default menu is empty. 


Parameters menuname is the resource name or number of the menu to be 
used. 


Example 


MENU errmenu 
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CLASS class 
Purpose This optional statement defines the class of the dialog box. 


Parameter class is an integer or a string (enclosed in double quotes) 
that identifies the dialog box class. 


Kzample 


CLASS "myclass" 


Control Statements 


The control statements, given in the control-definition section of the DIA- 
LOG statement, define the attributes of the control windows that appear 
in the dialog box. A dialog box is empty unless one or more control state- 
ments are given. 


Control statements have the following general form: 
control-type text, id, x, y, width, herght|, style] 


Three control statements are exceptions to this general form: the EDIT- 
TEXT and LISTBOX controls do not have a tezt field, and the custom 
control type, CONTROL, has one additional field, class. 


The control-type field is one of the keywords described below, defining the 
type of the control. 


text is an ASCII string specifying the text to be displayed. The string must 
be enclosed in double quotation marks. The manner in which the text is 
displayed depends on the particular control, as detailed below. 


td is a unique integer number identifying the control. 


zand y are integer numbers specifying the x and y coordinates of the upper 
left corner of the control. The coordinates are relative to the origin of the 
dialog box. | 


width and hetght are integer numbers specifying the width and height of the 
control. The width units are 1/4 the width of a character; the height units 
are 1/8 the height of a character. 


The x, y, width, and height fields can use addition and subtraction operators 


(+ and —) for relative positioning. For example, “15 + 6” can be used for 
the z field. 
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The optional style field consists of one or more of the control styles given 
later in this chapter in Table 6.2 and the window styles defined in Chapter 
2. Styles can be combined using the bitwise OR operator. 


The control-type keywords are described below, and their class and default 
style are given. See Tables 6.1 and 6.2 for a full description of control 
classes and styles. 


LTEXT 


Description 


Class 
Default Style 


RTEXT 


Description 


Class 
Default Style 


CTEXT 


Description 


Class 
Default Style 
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Left-justified text control. A simple rectangle displaying the 
given text left-justified in the rectangle. The tezt is format- 
ted before it is displayed. Words that would extend past the 
end of a line are automatically wrapped to the beginning of 
the next line. 


Static 
ES_ LEFT, WS_ GROUP 


Right-justified text control. A simple rectangle displaying 
the given tezt right-justified in the rectangle. The tezt is for- 
matted before it is displayed. Words that would extend 
past the end of a line are automatically wrapped to the 
beginning of the next line. 


Static 
ES— RIGHT, WS_ GROUP 


Centered text control. A simple rectangle displaying the 
given text centered in the rectangle. The tezt is formatted 
before it is displayed. Words that would extend past the 
end of a line are automatically wrapped to the beginning of 
the next line. 


Static 
ES_ CENTER, WS. GROUP 
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CHECKBOX 


Description 


A small rectangle (check box) that is highlighted when 
clicked. The given tezt is displayed just to the right of the 
check box. The control highlights the square when the user 


clicks the mouse in it, and removes the highlight on the next 
click. 


Class Button 

Default Style BS._CHECKBOX, WS_ TABSTOP 

PUSHBUTTON 

Description A rectangle containing the given text. The control sends a 
message to its parent whenever the user clicks the mouse 
inside the rectangle. 

Class Button 

Default Style BS._PUSHBUTTON, WS_ TABSTOP 

LISTBOX 

Description A rectangle containing a list of strings (such as filenames) 
from which the user can make selections. The LISTBOX 
control statement does not contain a tezt field, so the form 
of the LISTBOX statement is: 
LISTBOX id, z, y, cz, cy |, style 
The fields have the same meaning as in the other control 
statements. 

Class List box 

Default Style LBS_ NOTIFY, LBS_SORT, WS_ VSCROLL, WS—- BORDER 

GROUPBOX 

Description A rectangle that groups other controls together. The con- 
trols are grouped by drawing a border around them and 
displaying the given tezt in the upper left corner. 

Class Button 

Default Style BS_.GROUPBOX, WS_ TABSTOP 
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DEFPUSHBUTTON 


Description Asmall rectangle with an emboldened outline that 
represents the default response for the user. The tezt is 
displayed inside the button. The contro] highlights the 
button in the usual way when the user clicks the mouse in it 
and sends a message to its parent window. 


Class Button 
Default Style BS. DEFPUSHBUTTON, WS_ TABSTOP 


RADIOBUTTON 


Description Asmall rectangle that has the given text displayed just to its 
right. The control highlights the square when the user 
clicks the mouse in it and sends a message to its parent win- 
dow. The control removes the highlight and sends a mes- 
sage on the next click. 


Class Button 
Default Style BS_. RADIOBUTTON, WS_ TABSTOP 


EDITTEXT 


Description A rectangle in which the user can enter and edit text. The 
control displays a cursor when the user clicks the mouse in 
it. The user can then use the keyboard to enter text or edit 
the existing text. Editing keys include the backspace and 
delete keys. The mouse can be used to select the character 
or characters to be deleted, or select the place to insert new 
characters. 


The EDITTEXT control statement does not contain a tezt 
field, so its form is: 
EDITTEXT*d, 2, y, width, height |, style] 
The fields have the same meaning as in the other control 
statements. 

Class Edit 

Default Style WS TABSTOP, ES_ LEFT, WS_ BORDER 
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ICON 


Description An icon displayed in the dialog box. The given tezt is the 
name of an icon (not a filename) defined elsewhere in the 
resource file. 


For the ICON statement, the width and height parameters 
are ignored; the icon automatically sizes itself. 


Class Static 
Default Style SS_ICON 


CONTROL 


Description A user-defined control window. In addition to the standard 
control statement fields, the CONTROL statement con- 
tains class and style fields, as described below. The form of 
the statement is: 


CONTROL tezt, td, class, style, z, y, width, height 


class is a predefined name, character string, or integer 
defining the the class. It can be any one of the following: 


BUTTON 
STATIC 
EDIT 

" classname’ 
integer 


classname is an ASCII character string identifying a class. 


integer is an integer value identifying a class. 


style is a predefined name or integer number specifying the 
style of the given control. The exact meaning of style 
depends on the class value. Table 6.2 lists the control 
classes and corresponding styles. 


Class Depends on class field. 
Default Style None. 
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Table 6.1 


Control Classes 
Class Meaning 


BUTTON ~— A button control is a small rectangular child window 
that represents a “button” that the user can turn on or 
off by clicking on it with the mouse. Button controls 
can be used alone or in groups, and can either be 
labelled or appear without text. Button controls 
typically change appearance when the user clicks on 
them. 


EDIT An edit control is a rectangular child window in which 
the user can enter text from the keyboard. The user 
selects the control, and gives it the input focus, by 
clicking the mouse inside it or tabbing to it. The user 
can enter text when the control displays a flashing caret. 
The mouse can be used to move the cursor and select 
characters to be replaced, or position the cursor for 
inserting characters. The backspace key can be used to 
delete characters. 


Edit controls use the fixed-pitch font and display ANSI 
characters. They expand tab characters into as many 
space characters as required to move the cursor to the 
next tab stop. Tab stops are assumed to be at every 
eighth character position. 


STATIC Static controls are simple text fields, boxes, and 
rectangles that can be used to label, box, or separate 
other controls. Static controls take no input and 
provide no output. 


LISTBOX List box controls consist of a list of character strings. 
The control is used whenever an application needs to 
present a list of names, such as filenames, that the user 
can view and select. The user can select a string by 
pointing the mouse to the string and clicking a mouse 
button. Selected strings are highlighted and a 
notification message is passed to the parent window. A 
scroll bar can be used with a list box control to scroll 
lists too long or wide for the control window. 
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Table 6.1 (continued) 


Class Meaning 


SCROLLBAR ~~ Ascroll bar control is a rectangle containing a thumb 
and direction arrows at both ends. The scrolling bar 
sends a notification message to its parent whenever the 
user clicks the mouse in the control. The parent is 
responsible for updating the thumb position, if 
necessary. Scroll bar controls have the same appearance 
and function as the scroll bars used in ordinary 
windows. Unlike scroll bars, scroll bar controls can be 
positioned anywhere in a window and used whenever 
needed to provide scrolling input for a window. 

The scroll bar class also includes size box controls. A 
size box control is a small rectangle that the user can 
expand to change the size of the window. 


Note A control class name can be used as the class name 
parameter to the Create Window function to create a 
child window having the control class attributes. 
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Table 6.2 
Control Styles 


Style 
BUTTON Class 


BS_ PUSHBUTTON 

BS_ DEFPUSHBUTTON 
BS_ CHECKBOX 

BS_ AUTOCHECKBOX 


BS_ RADIOBUTTON 
BS_ 3STATE 


BS_ AUTO3STATE 


BS_ GROUPBOX 
BS_ USERBUTTON 


EDIT Class 


ES_ LEFT 
HS. CENTER 
ES RIGHT 
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Meaning 


Same as PUSHBUTTON statement. 
Same as DEFPUSHBUTTON statement. 
Same as CHECKBOX statement. 


Button automatically toggles its state whenever 
the user clicks on it. 


Same as RADIOBUTTON statement. 
Identical to BS. CHECKBOX except that a button 


can be grayed as well as checked or unchecked. 
The grayed state is typically used to show that a 
check box has been disabled. 


Identical to BS_ 3STATE except that the button 
automatically toggles its state when the user clicks 
on it. 


Same as GROUPBOX statement. 


User-defined button. Parent is notified when the 
button is clicked. Notification includes a request 
to paint, invert, and disable the button when 
necessary. 


Left-justified text. 
Centered text. 
Right-justified text. 


Table 6.2 (continued) 


Style 


ES MULTILINE 


ES_ AUTOVSCROLL 


ES_ AUTOHSCROLL 


ES_ NOHIDESEL 
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Meaning 


Multiple line edit control. (The default is single 
line.) If the AUTO_ VSCROLL style is specified, 
the edit control shows as many lines as possible 
and scrolls vertically when a carriage return/line 
feed combination (CR/LF) is typed (but not when 
just a line feed is typed). If AUTO_ VSCROLL is 
not given, the edit control shows as many lines as 
possible and beeps if the user enters CR/LF when 
no more lines can be displayed. 


If the ES_ AUTOHSCROLL style is specified, the 
multiple line edit control automatically scrolls 
horizontally when the caret goes past the right 
edge of the control. To start a new line, the user 
must enter a carriage return/line feed 
combination. If ES_ AUTOHSCROLL is not 
given, the control automatically word wraps when 
necessary; the user can also start a new line by 
entering CR/LF. The position of the word wrap is 
determined by the window size. If the window size 
changes, the word wrap position changes, and the 
text is redisplayed. 


Multiple line edit controls can have scroll bars. An 
edit control with scroll bars processes its own 
scroll bar messages. Edit controls without scroll 
bars scroll as described above, and process any 
scroll messages sent by the parent window. 


Text is automatically scrolled up one page 
vertically when the user presses the carriage 
return on the last line. 


Text is automatically scrolled horizontally to the 
right by 10 characters when the user types a 
character at the end of the line.. When the user 
presses the carriage return, the control scrolls all 
text back to position 0. 


Normally, an edit control hides the selection when 
it loses the input focus, and inverts the selection 
when it receives the input focus. Specifying 


ES NOHIDESEL overrides this default action. 
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Table 6.2 (continued) 


Style 
STATIC Class 


SS_ LEFT 

SS_ CENTER 

SS_ RIGHT 

SS_ ICON 

SS_ BLACKRECT 
SS_ GRAYRECT 
SS_ WHITERECT 
SS_ BLACKFRAME 
SS_ GRAYFRAME 
SS_ WHITEFRAME 
SS_ USERITEM 


LISTBOX Class 


LBS_ NOTIFY 


LBS_ MULTIPLESEL 


LBS_ SORT 


LBS_ NOREDRAW 
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Meaning 


Same as LTEXT control 
Same as CTEXT control 
Same as RTEXT control 
Same as ICON control 
Black filled rectangle 
Gray filled rectangle 
White filled rectangle 
Box with black frame 
Box with gray frame 
Box with white frame 


User-defined item 


The parent receives an input message whenever 
the user clicks or double clicks a string. 


The string selection is toggled each time the user 
clicks or double clicks on the string. Any number 
of strings can be selected. 


The strings in the list box are sorted 
alphabetically. 


The list box display is not updated when changes 
are made. This style can be changed at any time 


by sending a WM_SETREDRAW message. 


Table 6.2 (continued) 


Style 
SCROLLBAR Class 


SBS_ VERT 


SBS_ RIGHTALIGN 


SBS_ LEFTALIGN 


SBS_ HOIZ 


SBS_ TOPALIGN 


SBS_ BOTTOMALIGN 


SBS_ SIZEBOX 
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Meaning 


Vertical scroll bar. If neither SBS_ RIGHTALIGN 
nor SBS_ LEF TALIGN is specified, the scroll bar has 
the height, width, and position given in the control 
statement or the Create Window call. 


Used with SBS_ VERT. The right edge of the scroll 
bar is aligned with the right edge of the rectangle 
specified by the a, y, width, and height values given in 
the control statement (or in the CreateWindow 
call). The scroll bar has the default width for system 
scroll bars. 


Used with SBS_ VERT. The left edge of the scroll 
bar is aligned with the left edge of the rectangle 
specified by the z, y, width, and height values given in 
the control statement (or in the Create Window 
call). The scroll bar has the default width for system 
scroll bars. 


Horizontal scroll bar. If neither 

SBS_ BOTTOMALIGN nor SBS. TOPALIGN is 
specified, the scroll bar has the height, width, and 
position given in the control statement or the 
Create Window call. 


Used with SBS_HORZ. The top edge of the scroll 
bar is aligned with the top edge of the rectangle 
specified by the a, y, width, and height values given in 
the control statement (or in the CreateWindow 
call). The scroll bar has the default height for system 
scroll bars. 


Used with SBS_ HORZ. The bottom edge of the 
scroll bar is aligned with the bottom edge of the 
rectangle specified by the 2, y,; width, and height 
values given in the control statement (or in the 
Create Window call). The scroll bar has the default 
height for system scroll bars. 


Size box. If neither 

SBS_ SIZEBOXBOTTOMRIGHTALIGN nor 

SBS_ SIZEBOXTOPLEFTALIGN is specified, the 
size box has the height, width, and position given in 
the control statement or the CreateWindow call. 
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Table 6.2 (continued) 


Style 


SBS_ SIZEBOXTOPLEF TALIGN 


SBS_ SIZEBOXBOTTOMRIGHTALIGN 


All Classes 


WS_ GROUP 


WS_ TABSTOP 
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Meaning 


Used with SBS_ SIZEBOX. The top 
left corner of the size box is aligned 
with the top left corner of the rectangle 
specified by the z, y, width, and height 
values given in the control statement 
(or in the CreateWindow call). The 
size box has the default size for system 
size boxes. 


Used with SBS_ SIZEBOX. The 
bottom right corner of the size box is 
aligned with the bottom right corner of 
the rectangle specified by the g, y, 
width, and height values given in the 
control statement (or in the 

Create Window call). The size box 
has the default size for system size 
boxes. 


Specifies the first control of a group of 
controls in which the user can move 
from one control to the next by using 
the cursor keys. All controls defined 
after the first control with 

WS_ GROUP style belong to the same 
group. The next control with 

WS_ GROUP style ends the first group 
and starts the next group (i.e., one 
group ends where the next begins). 


Specifies one of any number of controls 
through which the user can move by 
tabbing. The TAB key moves the user 
to the next control with 


WS_ TABSTOP style. 


Examples 
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LTEXT “Enter Name:", 3, 10, 10, 40, 10 
RTEXT "Number of Messages", 4, 30, 50, 100, 10 
CrEAT “Title”... 3, 10, 50, 40. 10 


CHECKBOX 


PUSHBUTTON 
LISTBOX 666, 


“Arabic”, 3, 10, 10, 40, 10 
"ON", 7 16. 10. 20. 10 


LO, 10, SQ, 34 


GROUPBOX "Output", 42, 10, 10, 30, SO 
RADIOBUTTON "AM 101", 10, 10, 10, 40, 10 


EDITIEXL 3; 


10, 10, 100, 10 


6.2.7 Directives 


The resource directives are special statements that define actions to per- 
form on the script file before it is compiled. The directives can assign 
values to names, include the contents of files, and control compilation of 


the script file. 


The resource directives are identical to the directives used in the C pro- 
gramming language. They are fully defined in the Microsoft C Reference 


Manual. 


# include filename 


Purpose 


Parameters 


Example 


This directive copies the contents of the file specified by 
filename into your resource script before re processes the 
script. 


filename is an ASCII string, enclosed in double quotation 
marks, specifying the MS-DOS filename of the file to be 
included. A full pathname must be given if the file is not in 
the current directory or in the directory specified by the 
INCLUDE environment variable. 


The filename parameter is handled as a C string, and two 
backslashes must be given wherever one is expected in the 
pathname (for example, trey bee, ) Or, a single forward 
slash (/) can be used instead of double backslashes (for 
example, “root/sub”.) 


#include “windows.h" 


PenSelect MENU 
BEGIN 

MENUITEM "black pen", BLACK_PEN 
END 
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+#define name value 


Purpose 


Parameters 


Examples 


This directive assigns the given value to name. All subse- 
quent occurrences of name are replaced by the value. 


name is any combination of letters, digits, or punctuation. 


value is any integer number, character string, or line of text. 


#define nonzero 1 
#define USERCLASS "MyControlClass"” 


##undef name 


Purpose 


Parameters 


Examples 


+#ifdef name 


Purpose 


Parameters 


Example 
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This directive removes the current definition of name. All 
subsequent occurrences of name are processed without 
replacement. 


name is any combination of letters, digits, or punctuation. 


#unde f nonzero 
Hunde f USERCLASS 


This directive carries out conditional compilation of the 
resource file by checking the specified name. If the name has 
been defined using a # define directive, # ifdef directs the 
resource compiler to continue with the statement immedi- 
ately after it. If name has not been defined, # ifdef directs 
the compiler to skip all statements up to the next # endif 
directive. 


name is the name to be checked by the directive. 


#ifdef Debug 
errbox BITMAP errbox.bmp 
#endif 


File Formats 


# ifndef name 


Purpose This directive carries out conditional compilation of the 
resource file by checking the specified name. If the name has 
not been defined or if its definition has been removed using 
the # undef directive, #ifndef directs the resource com- 
piler to continue processing statements up to the next 
#- endif, #else, or # elif directive, then skip to the state- 
ment after after the # endif. If name is defined, #ifndef 
directs the compiler to skip to the next #endif, #else, or 
# elif directive. 


Parameters name is the name to be checked by the directive. 


Example 


#ifndef Optimize 
errbox BITMAP errbox.bmp 
#endif 


#if constant-ezxpresston 


Purpose This directive carries out conditional compilation of the 
resource file by checking the specified constant-ezpression. If 
the constant-expresston is nonzero # if directs the resource 
compiler to continue processing statements up to the next 
# endif, # else, or #elif directive, then skip to the state- 
ment after after the #endif. If constant-expresston is zero, 
#¢if directs the compiler to skip to the next # endif, # else, 
or # elif directive. 


Parameters —constant-expresston is a defined name, an integer constant, 
or an expression consisting of names, integers, and arith- 
metic and relational operators. 


Kzample 


#if Version<3 
errbox BITMAP errbox.bmp 
#endif 


#-elif constant-expression 


Purpose This directive marks an optional clause of a conditional 
compilation block defined by an # ifdef, # ifndef, or #if 
directive. The directive carries out conditional compilation 
of the resource file by checking the specified constant- 
expresston. If the constant-ezpression is nonzero # elif 
directs the resource compiler to continue processing state- 
ments up to the next # endif, # else, or # elif directive, 
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Parameters 


Kzample 


# else 


Purpose 


Parameters 


Ezample 


# endif 


Purpose 


Parameters 
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then skip to the statement after the # endif. If constant- 
expression is zero, 7 elif directs the compiler to skip to the 
next #tendif, #else, or #elif directive. Any number of 
# elif directives can be used in a conditional block. 


constant-expression is a defined name, an integer constant, 
or an expression consisting of names, integers, and arith- 
metic and relational operators. 


#if Version<3 

errbox BITMAP errbox.bmp 
#elif Version<7 

errbox BITMAP userbox.bmp 
#endif 


This directive marks an optional clause of a conditional 
compilation block defined by an # ifdef, # ifndef, or # if 
directive. The #else directive must be the last directive 


before # endif. 


None. 


#ifdef Debug 

errbox BITMAP errbox.bmp 
#else 

errbox BITMAP userbox.bmp 
#endif 


This directive marks the end of a conditional compilation 
block defined by an # ifdef directive. One # endif is 
required for each # ifdef directive. 


None. 
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6.3 Module Definition File 


The module definition file defines the contents and system requirements of a 
Windows application. The file contains one or more module statements, 
each defining a specific attribute of the application, such as its module 
name, the number and type of program segments, and the number and 
names of exported and imported functions. 


There are the following module statements: 


Statement 


NAME 
LIBRARY 
DESCRIPTION 
DATA 
CODE 
HEAPSIZE 
STACKSIZE 
SEGMENT 
EXPORTS 
IMPORTS 
STUB 


Description 


Module name 

Library name 

One line description of the module 
Data segment attributes 

Code segment attributes 

Local heap size in bytes 

Local stack size in bytes 
Additional code segment 
Exported functions 

Imported functions 


Old style executable 


The following are complete definitions of the module statements. 


NAME modulename 


Purpose This statement defines the name of the application’s execut- 
able module. The name is used to identify the module when 
importing or exporting functions. 


Parameters modulename is one or more ASCII characters. 


Example 


NAME Calendar 


311 


Microsoft Windows Reference Manual 


LIBRARY ltbraryname 


Purpose 


Parameters 
Notes 


Example 


This statement defines the name of a library module. 
Library modules are resource modules that contain code, 
data, and other resources but are not intended to be exe- 
cuted. 


libraryname is one or more ASCII characters defining the 
name of the library module. 


The start address of the module determined by the object 
files. It is an internally defined function. 


LIBRARY User 


DESCRIPTION tezt 


Purpose 


Parameters 


Example 


This statement inserts tezt into the application’s module. It 
is useful for embedding source control or copyright informa- 
tion. 


text is one or more ASCII characters. The string must be 
enclosed in single quotation marks. 


DESCRIPTION ‘Microsoft Windows Template Application' 


HEAPSIZE bytes 


Purpose 


Parameters 


Example 
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This statement defines the number of bytes needed by the 
application for its local heap. An application uses the local 
heap whenever it allocates local memory. 


The default heapsize is 0. 


bytes is an integer number specifying the heap size in bytes. 
It ~ 4 not exceed 65,536 (the size of a single physical seg- 
ment). 


HEAPSIZE 4096 
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STACKSIZE bytes 


Purpose This statement defines the number of bytes needed by the 
application for its local stack. An application uses the local 
stack whenever it calls its own functions. A minimum stack 
size of 4096 bytes is recommended. 


The default stack size is 0, if the application makes no func- 
tion calls. Otherwise, it is 4096. 


Parameters bytes is an integer number specifying the stack size in bytes. 


Example 
SOTACKSIZE 4096 


CODE memory-option load-option pure-option 


Purpose This statement defines the attributes of the application’s 
code segment. 


Parameters memory-optton is an optional keyword specifying whether 
the segment is fixed or moveable. It must be one of the fol- 


lowing: 

FIXED Segment remains at a fixed memory 
location 

MOVEABLE Segment can be moved if necessary to 


compact memory 


DISCARDABLE — Segment can be discarded if no longer 
needed 


The default is FIXED. 


load-opttion is an optional keyword specifying when the seg- 
ment is to be loaded. It must be one of the following: 


PRELOAD Segment is loaded immediately 
LOADONCALL Segment is loaded when called 
The default is PRELOAD. 
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pure-optton is an optional keyword specifying whether the 
segment is pure or impure. It must be one of the following: 


PURE Segment contains code only 
IMPURE Segment contains a mixture of code and data 
The default is PURE. 

Notes PURE and IMPURE are used for 286 protected mode pro- 


grams. 


Example 


CODE MOVEABLE LOADONCALL 


DATA memory-opttons instance-options 


Purpose This statement defines the attributes of the application’s 
data segment. The data segment contains the application’s 
local stack and heap. 


Parameters |memory-options is an optional keyword specifying whether 
the segment is fixed or moveable. It must be one of the fol- 


lowing: 

FIXED Segment remains at a fixed memory 
location 

MOVEABLE Segment can be moved if necessary to 


compact memory 


DISCARDABLE Segment can be discarded if no longer 
needed 


The default is FIXED. 


instance-options is an optional keyword that defines how 
many data segments are to be created for the module. It 
can be any one of the following: 


$14 


Example 


SEGMENT 
Purpose 


Parameters 
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NONE No data segment 
SINGLE A single segment to be shared by all 


instances of the module (valid only for 
library modules) 


MULTIPLE One segment for each instance 
The default is MULTIPLE. 


DATA MOVEABLE SINGLE 


segmeniname memory-option pure-opttion load-option 
minalloc 


This statement defines an additional code segment for appli- 
cations that use a middle model memory organization. 


segmentname is a character string naming the new segment. 
It can be any name, including the predefined segment names 
“_ TEXT” or “_ DATA” that represent the CODE and 
DATA segments. Redefining the CODE or DATA segment 
changes that segment’s default values. 


memory-option is an optional keyword specifying whether 
the segment is fixed or moveable. It must be one of the fol- 
lowing: 


FIXED Segment remains at a fixed memory 
location 
MOVEABLE Segment can be moved if necessary to 


compact memory 


DISCARDABLE — Segment can be discarded if no longer 


needed 
The default is FIXED. 


pure-optton is an optional keyword specifying whether the 
segment is pure or impure. It must be one of the following: 


PURE Segment contains code only 
IMPURE Segment contains a mixture of code and data 
The default is PURE. 
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Notes 


Example 


EXPORTS 


Purpose 


Parameters 
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load-optton is an optional keyword specifying when the seg- 
ment is to be loaded. It must be one of the following: 


PRELOAD Segment is loaded immediately 
LOADONCALL Segment is loaded when called 
The default is PRELOAD. 


minalloc is an optional integer number specifying the 
minimum number of bytes to be allocated for this segment. 


PURE and IMPURE are used for 286 protected mode pro- 
grams. 


SEGMENTS 
_TEXT FIXED 
_INIT PRELOAD MOVEABLE DISCARDABLE 15 
_RES PRELOAD MOVEABLE DISCARDABLE 8 


exportname ordinal-option res-option data-optton parameter- 
option 


This statement defines the names and attributes of the func- 
tions to be exported to other applications. The EXPORTS 
keyword marks the beginning of the definitions. It can be 
followed by any number of export definitions, each on a 
separate line. 


exportname is one or more ASCII characters defining the 
function name. It has the form: 


entryname|—tnternalname| 


where entryname is the name to be used by other applica- 
tions to access the exported function, and tnternalname is an 
optional parameter that defines the actual name of the func- 
tion if entryname is not the actual name. . 


ordtnal-optton is an optional parameter defining the 
function’s ordinal value. It has the form: 


@ ordinal 


where ordinal is an integer number specifying the function’s 
ordinal value. The ordinal value defines the location of the 
function’s name in the application’s string table. 


Example 
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res-opttion is the optional keyword RESIDENTNAME 
specifying that the function’s name must be resident at all 
times. 


data-option is the optional keyword NODATA specifying 
that the function is not bound to a specific data segment. 
When invoked, the function uses the current data segment. 


parameter-option is an optional integer number specifying 
the number of words the function expects to be passed as 
parameters. 


EXPORTS 
sampleRead=read2bin @l 8 
StringIn=strl @2 4 
CharTest NODATA 


IMPORTS internal-option modulename entry-option 


Purpose 


Parameters 


This statement defines the names and attributes of the func- 
tions to be imported from other applications. The 
IMPORTS keyword marks the beginning of the definitions. 
It can be followed by any number of import definitions, each 
on a separate line. 


wnternal-option is an optional parameter specifying the name 
that the application will use to call the function. It has the 
form: 


internal-name= 


where internal-name is one or more ASCII characters. This 
name must be unique. 


modulename is the name of the executable module contain- 
ing the function. 
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entry-option is an optional parameter specifying the function 
to be imported. It can be one of the following: 


.entryname 
.entryordinal 


where entryname is the actual name of the function, and 
entryordinal is the ordinal value of the function. 


Example 


IMPORTS 
sample.SampleRead 
writezZhex=Sample.SampleWrite 
Read. 1 


STUB filename 


Purpose This statement appends the old style executable file given by 
filename to the beginning of the module. The executable 
stub should display a warning message and terminate if the 
user attempts to execute the module without having loaded 


Windows. The default file WINSTUB.EXE can be used if no 


other actions are required. 


Parameters __ filename is the name of the old style executable file to 
append to the module. The name must have the MS-DOS 


filename format. 


6.4 Windows Initialization File 


A Windows initialization file is a list of application names and option 
values that applications can access when executing. The Windows initiali- 
zation file defines what initial values the user would like application-specific 
options to have. Each option has a corresponding keyname and value. 


The Windows initialization file is kept in a special control file, named 
WIN.INI, that Windows searches for in the Windows boot directory (the 
current working directory at the time the user invoked Windows). If not 
found in the boot directory, Windows searches the directories given in the 
PATH environment variable, stopping with the first WIN.INI file it finds. If 
it finds the file, it reads its contents and performs the specified actions. 
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The WIN.INI file is an ordinary text file that you can create using a text 
editor. It has the general form 


in mnie sy 
eyname = value 


where [application-name] is the name of an application (usually the filename 
of the module file containing the application). The enclosing brackets ({]) 
are required. keyname = value is a special line defining the value of specific 
options associated with the application. 


You can also place comments in a file. A comment may be placed on any 
line in which the first non-space character is a semicolon (;). 


Applications can also access and change settings in WIN.INI during a Win- 
dows session. However, since WIN.INI is shared by all Windows applica- 
tion, any application that makes a change to sections of WIN.INI that 
could affect other applications is responsible for notifying other applica- 


tions of the change with the WM_ WININICHANGE message. 


You can give any number of application names. Each name can be followed 
by one or more keyname-and-value lines. A keyname-and-value line that 
appears immediately below an application name belongs to that applica- 
tion. 


A keyname is the name of an option. It can consist of any combination of 
letters and digits, but must be followed immediately by the equal sign (=). 
A value is the option’s value. It can be any one of the following: 


Value Description 
Integer Must use decimal digits. 
String Can be any combination of letters, digits, and punctua- 


tion. Leading spaces are ignored. 


Quoted string Can be any combination of letters, digits, and punctua- 
tion, but must be enclosed in double quotation marks. 
Spaces within the quotation marks are not ignored. A 
pair of quotation marks ("") in the string are treated as a 
single mark. 
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6.4.1 Windows Section 
Syntax 


[windows] 

Run = list 

Load = list 

Device = output-device-name, device-driver, port-connection 
DoubleClickSpeed—=milliseconds 
CursorBlinkRate=milliseconds 
NullPort—null-portname 


The windows section contains optional settings that take effect when Win- 
dows is first invoked. The Run and Load fields tell Windows to load a 
particular application or applications when Windows is first started. The 
list parameter is a list of one or more application filenames, separated by 
commas or whitespace. (Commas have a special meaning in the Run line, 
as described below.) 


All applications listed in the Load line are run and placed in the icon area 
when Windows is first started. All applications listed in the Run line are 
run and displayed as windows when Windows is first started. A comma 
separating one application name from the next in the Run line means that 
the next application will be displayed in a new column. If only whitespace 
separates two application names in the Run line, the applications will be 
displayed in the same column. 


The Device field defines the default output device. This is the device used 
for all printer output if no explicit device is given. The output-device-name 
can be any device name given in the devices section. An explicit port and 
driver must be assigned to the device. The user can set the printer mode in 
the control panel. device-driver is the module name (that is, the filename 
without the extension) of the device driver file. port-name is any port name 
given in the ports section. 


The DoubleClickSpeed field sets the system’s double click speed in mil- 
liseconds. 


The CursorBlinkRate field sets the blinking rate (in milliseconds) for the 
system cursor. 


The NullPort field sets the name used for a null port to null-portname. 
This name is used by the control panel and spooler (and other applications) 
in cases where a device is installed (that is, the device driver is present), but 
is not connected to any port. 
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6.4.2 Ports Section 
Syntax 


[ports] 
portname:—baud-rate, parity, word-length, stop-bits 


The ports section enumerates all available communication ports and 
defines default modes or settings. The portname must be the name of the 
communication port as it is recognized by MS-DOS. 


The baud-rate gives the port’s baud rate. 

The parity setting is ’o’, ’e’, or ’n’, for odd, even, or none, respectively. 
The word-length field gives the length of a word, in bits. 

The stop-btts field gives the number of stop bits to be used. 


6.4.3 Colors Section 
Syntax 


[colors] 
component=—redvalue greenvalue bluevalue 


The Color section defines the background color for the specified component 
of the Windows display screen. The component can be any one of the fol- 
lowing: 


Name Component 

Scrollbar Scroll bar 

Background Icon area and screen background 
ActiveTitle Active caption bar 

Inactive Title Inactive caption bar 

Menu Menu background 

Window Window client area background 
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WindowF rame Title background and frame color 
Menu Text Menu text 

Window Text Window text 

TitleText Title text 


redvalue is an integer number specifying the intensity of red in the back- 
ground. It can be any value from 0 to 255. greenvalue is an integer number 
specifying the intensity of green in the background. It can be any value 
from 0 to 255. dbluevalue is an integer number specifying the intensity of 
blue in the background. It can be any value from 0 to 255. 


Note 


Windows expects a solid color for menu (MenuText), window (Win- 
dowText), and title text (TitleText) and for the window background 
(Window). The GetNearestColor function can be used to obtain the 
nearest system color. 


6.4.4 Devices Section 
Syntax 


[devices] 
device-name—driver-name, port-name |, portname...] 


The devices section names the output devices that can be accessed by Win- 
dows device drivers and specifies the communications port or ports to which 
the devices are connected. If a device is not currently connected, the port- 
name parameter should be the string specified in the NullPort field of the 
windows section of WIN.INI. 
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6.4.5 Fonts Section 
Syntax 


[fonts] 
font-name=font-file 


The fonts section describes one or more font files that are loaded by Win- 
dows when it is booted. font-name is the descriptive name of a font. font- 
file is the filename, without the extension, of a file containing font 
resources. 


Note 


An application can use the EnumFonts function to obtain information 
about the currently available fonts. 


6.4.6 International Section 
Syntax 


[intl] 
itemname=—value 


The intl section describes how to display dates, times, dollar amounts, and 
other items in countries other than the U.S. Windows does not require the 
intl section in U.S. versions of WIN.INI. Any application that uses the intl 
section must supply its own default value when calling GetProfileString 
to retrieve a value from this section. 


The ttemname and corresponding value can be any one of the following: 


Name Value 

iCountry Country Code (see the COUNTRY command in MS-DOS 3.0 
Reference Manual) 

iDate 0 for month-day-year 


1 for day-month-year 
2 for year-month-day 
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iCurrency 


iDigits 


1lime 
iLzero 


s1159 
$2359 
sCurrency 
sThousand 
sDecimal 
sDate 
sTime 
sList 
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0 for currency symbol prefix, no separation 
1 for currency symbol suffix, no separation 
2 for currency symbol prefix, 1 character separation 
3 for currency symbol suffix, 1 character separation 


Number of significant decimal digits in currency 


0 for 12 hour clock 
1 for 24 hour clock 


0 for no leading zeros 
1 for leading zeros 


Trailing string from 0:00 to 11:59 
Trailing string from 12:00 to 23:59 
Currency symbol string 
Thousands separator string 
Decimal separator string 

Date separator string 

Time separator string 


List separator string 


Chapter 7 
Assembly Language Macros 


ved 

1.2 

1.3 

7.3.1 
7.3.2 
7.3.3 
7.3.4 
7.4 

7.4.1 
7.4.2 
7.4.3 
7.4.4 
7.4.9 
7.9 

7.0.1 
7.9.2 
7.9.93 


Introduction 327 
CMACROS.INC File 327 
Cmacros Options 327 
Memory Model Selection 328 
Calling Conventions 329 
Windows Prolog/Epilog 330 
Stack Checking Option 330 
Segment Macros = 33] 
Storage Allocation Macros 334 
Function Macros 337 
Call Macros 341 
Special Definition Macros 343 
Error Macros 345 
Using the Cmacros 346 
Overriding Types 346 
Symbol Redefinition 347 
Cmacros: A Sample Function 347 


325 


Assembly Language Macros 


7.1 Introduction 


This chapter describes the Cmacro macros, a set of assembly-language 
macros that can be used with the Microsoft Macro Assembler (MASM) to 
create assembly-language Windows applications. The Cmacros provide a 
simplified interface to the function and segment conventions of high-level 
languages, such as C and Pascal. 


The Cmacros are divided into the following groups: 


Segment Macros 

Storage Allocation Macros 
Function Macros 

Call Macros 

Special Definition Macros 
Error Macros 


The following sections describe each group in detail. 


7.2 CMACROS.INC File 


The file CMACROS.INC contains the assembly-language definitions for all 
the Cmacro macros. This file must be included at the beginning of the 
assembly source file by using the INCLUDE directive. The line has the 


form: 
INCLUDE cmacros.inc 


A full pathname must be given if the macro file is not in the current work- 
ing directory or not in a directory specified on the command line. 


7.3 Cmacros Options 


The Cmacros provide assembly-time options that define the memory 
model and the calling conventions to be used by the application. The 
options must be selected prior to the INCLUDE directive used to include 
the CMACROS.INC file. 
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7.3.1 


Memory Model Selection 


The memory model options specify the memory model to be used by the 
application. The memory model defines how many code and data segments 
are in the application. There are the following memory models: 


Model 


Small Model 
Middle Model 
Large Model 
Compact Model 


Huge Model 


Definition 


One code and one data segment. 
Multiple code segments and one data segment. 
Multiple code and data segments. 


One code segment and multiple data seg- 
ments. 


Multiple code segments and multiple data seg- 
ments with one or more data items larger than 
64K bytes. 


The memory option is selected by defining one of the following option 
names shown in Table 7.1 at the beginning of the assembly-language source 


file. 


Table 7.1 


Memory Options 


Option 
Name 


memS 
memM 
memL 
memC 


memH 


A name can be defined by using the EQU directive. The definition has the 


form: 


memM EQU 


If no option is selected, the default is “memS” or small model. 
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Memory Code Data 
Model Size Size 
small small small 
medium large small 
large large large 
compact small large 
huge large large 
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Selecting a memory model option results in the definition of two symbols 
that can be used for memory model dependent code: 
SizeC O—smallcode 1 = large code 


SizeD 0 =—smalldata 1=largedata 2 = huge data 


7.3.2 Calling Conventions 


The calling convention option specifies the high-level language calling con- 
vention to be used by the application. The calling convention is selected by 
defining the value of the symbol 7PLM. The following table lists the 
values and conventions: 


Table 7.2 

Calling Conventions 

?PLM value Convention Description 

0 Standard C The caller pushes the right-most 


argument onto the stack first, the 
left-most last. The caller pops 
the arguments off the stack after 
control is returned. 

1 Pascal The caller pushes the left-most 
argument onto the stack first, the 
right-most last. The called 
function pops the arguments off 
the stack. 


The ?7PLM symbol value can be set using the directive. The statement 
has the form: 


?PLM = 1 


The default is the Pascal convention. 
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7.3.3. Windows Prolog/Epilog 


The Windows prolog/epilog option specifies whether or not special prologue 
and epilogue code should be used with each function. This special code 
defines the current data segment for the given function and is required for 
Windows applications. 


This option is selected by defining the value of the symbol ?WIN. The fol- 
lowing table lists the values and conventions: 


Table 7.3 
Prolog /Epilog Code Options 


?WIN value Meaning 


—s 


0 Disables the special prolog/epilog code. 
1 Enables the special prolog/epilog code. 


The ?WIN symbol value can be set using the —directive. The statement 
has the form: 


?WIN = 1 


The default is the Windows prolog/epilog. 


7.3.4 Stack Checking Option 


Stack checking can be enabled by defining the symbol 7CHKSTK. When 
enabled, the prologue code calls the externally defined routine CHKSTK 
to allocate local variables. 


The ?CHKSTK symbol can be defined using the —directive. The state- 
ment has the form: 


?CHKSTK = 1 


Once CHKSTK is defined, stack checking is enabled for the entire file. 
The default (when CHKSTK is not defined) is no stack checking. 
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7.4 Segment Macros 


The segment macros give access to the code and data segments to be used 
in an application. These segments have the names, attributes, classes, and 
groups required by Windows. 


The Cmacros have two predefined segments, named CODE and DATA, 
that any application can use without special definition. Middle, large, and 
huge model applications can define additional segments using the 
createSeg macro. 


createSeg segName, logName, align, combine, class 


Purpose 


Parameters 


This macro creates a new segment having the specified name 
and segment attributes. The macro automatically creates 
an assumes macro and OF FSET equate for the new seg- 
ment. This macro is intended to be used in middle model 
Windows applications to define non-resident segments. 


segName is the actual name of the segment. This name is 
passed to the linker. 


logName is the logical name of the segment. This name is 
used in all subsequent sBegin, sEnd, and assumes macros 
that refer to the segment. 


align is the alignment type. It can be any one of the follow- 
ing: 


BYTE 
WORD 
PARA 
PAGE 


combine is the combine type for the segment. It can be any 
one of the following: 


PUBLIC 
STACK 
MEMORY 
COMMON 


If no combine type is given, a private segment is assumed. 
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Example 


Notes 


class is the class name of the segment. The class name 
defines which segments must be loaded in consecutive 
memory. 


createseg _INIT, INITCODE, BYTE, PUBLIC, CODE 


sBegin INITCODE 
assumes CS: INITCODE 


mov ax,initcodeOFFSET sample 


sEnd INI TCODE 


The alignment, combine type, and class name are described 
in detail in the Microsoft Macro Assembler Reference 
Manual. 


sBegin segName 


Purpose 


Arguments 


Examples 


This macro opens up a segment. It is similar to the SEG- 
MENT assembler directive. 


segName is the name of the segment to be opened. It can be 
one of the predefined segments, CODE or DATA, or the 


name of a user-defined segment. 


sBegin DATA 
sBegin CODE 


sEnd segName 


Purpose 


Arguments 


Kzamples 
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This macro closes a segment. It is similar to the ENDS 
assembler directive. 


segName is an optional name used for readability. If given, 
it must be the same name given in the matching sBegin 
macro. 


sEnd 
sEnd DATA 
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assumes segleg, segName 


Purpose 


Arguments 


Examples 


This macro makes all references to data and code in the seg- 
ment segName relative to the segment register given by 
segReg. It is similar to the ASSUME assembler directive. 


segReg is the name of a segment register. 


segName is the name of a predefined segment, CODE, or 
DATA, or a user-defined segment. 


assumes CS, CODE 
assumes DS, CODE 


dataOFFSET arg 


Purpose 


Parameters 


Example 


This macro generates an offset relative to the start of the 
group to which the DATA segment belongs. It is similar to 
the OF FSET assembler operator, but automatically pro- 
vides the group name. For this reason, it should be used 
instead of OFFSET. 


arg is a label name or offset value. 


mv ax,dataOFFSET label 


codeOF FSET arg 


Purpose 


Parameters 


Example 


This macro generates an offset relative to the start of the 
group to which the CODE segment belongs. It is similar to 
the OF FSET assembler operator, but automatically pro- 
vides the group name. For this reason, it should be used 


instead of OFFSET. 


arg is a label name or offset value. 


mv ax,codeOFFSET label 
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segNameOFFSET arg 


Purpose This macro generates an offset relative to the start of the 
group to which the user-defined segment segName belongs. 
It is similar to the OF FSET assembler operator, but 
automatically provides the group name. For this reason, it 
should be used instead of OFFSET. 


Parameters  argisa label name or offset value. 


Example 


mv ax, initcodeOFFSET label 


7.4.1 Storage Allocation Macros 


These macros allocate static memory (either private or public), declare 

externally defined memory and procedures, and allow the definition of pub- 

lic labels. 

staticX name, initial Value, replication 

Purpose This macro allocates private static memory storage. 

Arguments X is the size of storage to be allocated. It can be any one of 
the following: 

B Byte 

W Word 

D Double word 

Q Quad word 

T Ten bytes 


CP Code Pointer (1 word for small and compact 
models) 


DP Data Pointer (1 word for small and middle 
models) 


name is the reference name of the allocated memory. 


wntttal Value is an optional initial value for the storage. 
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replication is an optional count of the number of times the 
allocation is to be duplicated. This argument generates the 
DUP assembler operator. 


staticW flag,1l 
statice stririg, , 30 


globalX name, initial Value, replication 


Purpose 


Arguments 


Examples 


This macro allocates public static memory storage. 


X specifies the size of the storage to be allocated. It can be 


any one of the following: 


B Byte 

W Word 

D Double word 
Q Quad word 
T Ten bytes 


CP Code Pointer (1 word for small and compact 
models) 


DP Data Pointer (1 word for small and middle 
models) 
name is the reference name of the allocated memory. 
tntttal Value is the initial value for the storage. 


replication is an optional count of the number of times the 
allocation is to be duplicated. This argument generates the 
DUP assembler operator. 


globalW flag,1l 
globalB string,O, 30 


335 


Windows Reference Manual 


externX <nameltst> 


Purpose This macro defines one or more public (global) variables or 
functions. 


Arguments X specifies the storage size or function type. It can be any 
one of the following: 


B Byte 

W Word 

D Double word 

Q Quad word 

@ Ten bytes 

CP Code Pointer (1 word for small and compact 
models) 

DP Data Pointer (1 word for small and middle 
models) 

NP Near Function 

FP Far Function 

P Near for small and compact models; Far for 


other models 


namelist is the name list of the variables or functions. 
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externB <DataBase> 
externFP <SampleRead> 
labelX <nameltst> 


Purpose This macro defines a label for one or more external variables 
or functions. 


Arguments X specifies the storage size or function type. It can be any 
one of the following: 


B Byte 
W Word 
D Double word 
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Q Quad word 

z Ten bytes 

CP Code Pointer (1 word for small and compact 
models) 

DP Data Pointer (1 word for small and middle 
models) 

NP Near Function 

FP Far Function 

E Near for small and compact models; Far for 


other models 
nameltst is the name list of the external variables or func- 
tions. 


Examples 


labelB <DataBase> 
labelFP <Sampl1eRead> 


7.4.2 Function Macros 


The function macros define the names, attributes, parameters, and local 
variables of functions. 

cProc procName, <attributes>, <autoSave> 

Purpose This macro defines the name and attributes of a function. 
Arguments —_procName is the name of the function. 


attributes specify the function type. They can be a combina- 
tion of the following: 


NEAR A near function. It'can only be called from 
the segment in which it is defined. 

FAR A far function. It can be called from any 
segment. 


PUBLIC A public function. It can be externally 
declared in other source files. 
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The default attribute is NEAR and private (i.e., cannot be 
declared externally in other source files). The NEAR and 
FAR attributes cannot be used together. If more than one 
attribute is selected, the angle brackets are required. 


autoSave specifies a list of registers to be saved when the 
function is invoked and restored when exited. Any of the 
8086’s registers can be specified. If more than one register is 
listed, the angle brackets are required. 


Examples 
cProc procl, <FAR>, <ds,es> 
cProc proc2, <NEAR,PUBLIC> 
cProc procs, ,.ds 
Notes The C calling conventions require that the SI and DI regis- 


ters be saved if they will be altered. 


The BP register is always saved, regardless of whether it is 
present in the autoSave list. 


parmX <namelist> 


Purpose This macro defines one or more function parameters. The 
parameters provide access to the arguments passed to the 
function. Parameters must appear in the same order as the 
arguments in the function call. 


Arguments X specifies the storage size. It can be any one of the follow- 
ing: 


es 


Byte (allocated on a word boundary on the 
stack) 


Word (allocated on a word boundary) 
Double word (allocated on a word boundary) 
Quad word (aligned on a word boundary) 


Ten byte word (aligned on a word boundary) 


QxHOUs 


P Code Pointer (1 word for small and compact 
models) 


DP Data Pointer (1 word for small and middle 
models) 
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namelist is the name list of the parameters. If more than 
one parameter is given, the angle brackets are required. 


ParmwW varl 
ParmB <var2,var3,var4> 
ParmD <var5> 


The parmD macro creates two additional symbols, 
OFF_ name and SEG_ name. OF F_ name is the offset por- 
tion of the parameter; SEG_ name is the segment portion. 


Only the parameter name is required when referencing the 
corresponding argument. 


Code: mov a war 1 


Not: mov al, byte ptr varl [bp] 


LocalX <namelist>, size 


Purpose 


Arguments 


This macro defines one or more frame variables for the func- 
tion. To maintain word alignment of the stack, the macro 
ensures that the total space allocated is an even number of 
bytes. It is assumed that the stack was on a word boundary 
upon entry into the function. 


X specifies the storage size. It can be any one of the follow- 


ing: 
B Byte (allocates a single byte of storage on the 

stack) 

Word (allocated on a word boundary) 

Double word (allocated on a word boundary) 

Variable size (allocated on a word boundary) 


Quad word (aligned on a word boundary) 


HOo<d0 se 


Ten byte word (aligned on a word boundary) 
CP Code pointer (same as used elsewhere) 
DP Data pointer (same as used elsewhere) 
namelist is the name list of the frame variables for the func- 


tion. If more than one parameter is given, the angle brack- 
ets are required. 
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Examples 


Notes 


size specifies the size of the variable. It is used with local V 
only. 


LocalB <L1,L2,L3> 
LocalW L4 

LocalD <L5> 

LocalV L6,%(size struc) 


B type variables are not necessarily aligned on word boun- 
daries. 


The localD macro creates two additional symbols, 
OFF_ name and SEG_ name. OF F_ name is the offset por- 
tion of the parameter; SEG_ name is the segment portion. 


Only the name is required when referencing a variable. 
Code: mov al,varl 


Not: mov al,byte ptr varl[bp] 


cBegin procName 


Purpose 


Arguments 


This macro defines the actual entry point for the function 
procName. The macro creates code that sets up the frame 
and saves registers. 


procName is an optional function name. If given, it must be 
the same as given in the cProc macro immediately preced- 
ing the cBegin macro. 


cEnd procName 


Purpose 


Arguments 


This macro defines the exit point for the function proc- 
Name. The macro creates code that discards the frame, 
restores registers, and returns to the caller. 


procName is an optional function name. If given, it must be 
the same as given in the cBegin macro immediately preced- 
ing the cEnd macro. 


Once a function has been defined using cProc, any formal parameters 
should be declared with the parmX macro and any local variables with the 
localX macro. The cBegin and cEnd macros must be used to delineate 
the code for the function. The following is an example of a complete func- 


tion definition: 
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cProc strcpy, <PUBLIC>,<si,di> 


parmW 
parmW 


dst 
src 


localW cnt 


cBegin 
cld 
mov 
mov 
push 
pop 
xor 
mov 

loop: 
lodsb 
stosb 
inc 
cmp 
jnz 
mov 

cEnd 


7.4.3 Call 


si,src 
di,dest 
ds 

es 

Cx; Cx 
Cnt, 2x 


cnt 
al,O 
loop 
ax,cnt 


Macros 


The call macros can be used to call cProc functions and high-level 
language functions. These macros pass arguments according to the calling 
convention defined by the 7PLM option. 


cCall procName, <arglist >, underscores 


Purpose 


Arguments 


This macro pushes the arguments in the argList onto the 
stack, saves registers (if any), and calls the function proc- 
Name. 


procName is the name of the function to be called. 


argList is an optional list of the names of arguments to be 
passed to the function. This list is not required if the Arg 
macro is used before the cCall. If more than one argument 
is given, the angle brackets are required. 


underscores is an optional value that specifies whether or 
not an underscore should be prepended to procName. If this 
argument is blank, an underscore is prepended. 
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Examples 


Notes 


cCall there, <pExt,ax,bx,pResult> 


Arg pExt 
Arg ax 
cCall there, <bx, pResult> 


The arguments of an Arg macro are pushed onto the stack 
before any arguments in the argList of a cCall macro. 


Byte type parameters are passed as words. There is no sign 
extension or zeroing of the high-order byte. 


Immediate arguments are not supported. 


Save <reglist> 


Purpose 


Arguments 


Examples 


This macro directs the next cCall macro to save the 
specified registers on the stack before calling a function, and 
to restore the registers after the function returns. The 
macro can be used to save registers that are destroyed by 
the called function. 


The Save macro applies to one cCall macro only; each new 
cCall must have a corresponding Save macro. If two Save 
macros appear before a cCall, only the second macro is 
recognized. 


regList is a list of registers to be saved. If more than one 
register is given, the angle brackets are required. 


Save <cl,bh,si> 
Save <ax> 


Arg <namelList> 


Purpose 


$42 


This macro defines the arguments to be passed to a function 
by the next cCall macro. The arguments are pushed onto 
the stack in the order given. This order must correspond 
with the order of the function parameters. 


More than one Arg macro can be given before each cCall. 
Multiple Arg macros have the same effect as a single macro. 


Arguments 


Examples 


Notes 
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nameList is a list of argument names to be passed to the 
function. All names must have been previously defined. 


If more than one name is given, the angle brackets are 
required. 


Arg varl 
Arg var2 
Arg var3 
Arg <varl,var2,var3> 


Byte type parameters are passed as words. There is no sign 
extension or zeroing of the high-order byte. 


Immediate arguments are not supported. 


7.4.4 Special Definition Macros 


The special definition macros inform the Cmacros about user-defined vari- 
ables, function register use, and register pointers. 


DefX <namelist > 


Purpose 


Arguments 


This macro registers the name of a user-defined variable 
with the Cmacros. Variables that are not defined using the 
staticX, globalX, externX, parmX, or localX macros 
cannot be referred to in other macros unless the name is 
registered, or the variable was defined with the DW assem- 
bler directive. 


X specifies the storage size of the variable. It can be any one 
of the following: 


B Byte 

W Word 

D Double word 

Q Quad word 

T Ten byte word 

CP Code pointer (same as used elsewhere) 
DP Data pointer (same as used elsewhere) 


nameltst is a list of variable names to be defined. 
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Example 


maxSize db L132 
DefB maxsize 
dest equ wordptr es: [di] 
De fW dest 


RegPtr name, segment, offset 


Purpose This macro defines a 32-bit value that is contained in the 
registers given by segment and offset. It allows the 32-bit 
value to be passed as a single argument in a cCall macro. If 
the RegPtr macro is not used, the result of the cCall 
macro is dependent on the calling conventions because the 
order in which the arguments are pushed could differ. 


Arguments name is the name of the pointer to be created. 


segment is the name of the register to contain the segment 
portion of the pointer. 


offset is the name of the register to contain the offset portion 
of the pointer. 


Example 


RegPtr destPtr,es,di 
cCall proc, <destPtr,ax> 
FarPtr name, segment, offset 


Purpose This macro defines a 32-bit pointer value that can be passed 
as a single argument in a cCall macro. Unlike the RegPtr 
macro, the segment and offset values do not have to be in 
registers. 


Arguments name is the name of the pointer to be created. 


segment is the text defining the segment portion of the 
pointer. ; 


offset is the text defining the offset portion of the pointer. 
Example 


FarPtr destPtr,es,<wordptr 3[si]> 
cCall proc, <destPtr,ax> 
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7.4.5 Error Macros 


The error macros allow assertions to be coded into an assembly source pro- 
gram. This allows the coding of optimum instruction sequences for some 
operations based on variable allocation or bit position of a flag in a word, 
and asserting that the assumptions made are true. 


Error macros generate an error message to the console and an error message 
in the listing. Both the text that caused the error, and the result of its 
evaluation, is displayed in the generated error message. 


errnz <exzpression> 


Purpose 


Arguments 


Examples 


This macro evaluates a given expression. If the result is not 
zero, an error is displayed. 


expression is the expression to be evaluated. The angle 
brackets are required if there are any spaces in the expres- 
sion. 


x db ? 
y db ? 
mov ax, word ptr x 


errnz <(OFESET vy) - (OFFSET x) -1> 


If during assembly z and y receive anything but sequential 
storage locations, errnz displays an error message. 


tablel struc 

tablellen equ $-tablel 
tablel ends 

table2 struc 

table2len equ $-table2 
table2 ends 


errnz tablelLen-table2Len 


If during assembly the length of two tables is not the same, 
errnz displays an error message. 
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errns label, bias 


Purpose This macro subtracts the offset of label from the offset of the 
location counter, then adds bias to the result. If this result 
is not zero, then an error message is displayed. 


Arguments labelis a label corresponding to a memory location. 
btas is a signed bias value. A plus or minus sign is required. 


Example 


end of previous code 
errns functionl 
functionl: 


If a function originally located immediately after another 
piece of code is ever moved, errn} displays an error mes- 
sage. 


7.5 Using the Cmacros 


This section explains the assembly-language statements generated by some 
of the Cmacros and illustrates their use with an example of a Cmacros 


function called “BITBLT.” 


7.9.1 Overriding Types 


Parameters and local variables created using the parmX and localX mac- 
ros actually correspond to expressions of the form: 


LocalB x ==> x equ byte ptr [bptnn] 
ParmB y ==> y equ byte ptr [bptnn] 


where nn is an offset from the current BP register value. 


These expressions allow the usage of the names without having to explicitly 


type in “type ptr” and “|BP]|+offset” operators. This means “x” can be 
referred to as 


mov al. x 
and “y” as: 
mov ax,y 
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A problem arises if the type must be overridden. The assembler creates an 
error message if it encounters the line: 


mov ax,word ptr x 
This can be solved by enclosing the name in parentheses: 
mov ax,word ptr (x) 


One exception to the above is the LocalV macro. The expression generated 
by this macro does not have a type associated with it. Therefore it can be 
overridden without the parentheses. For example: 


LocalV horse,10 ==> horse equ [bptnn] 


7.9.2 Symbol Redefinition 


Any symbol defined by a parmX in one function can be redefined as a 
parameter in any other function. This allows different functions to refer to 
the same parameter by the same name, regardless of its location on the 
stack. 


7.9.0 Cmacros: A Sample Function 


The following example defines an assembly function “BITBLT.” BITBLT is 
a FAR and PUBLIC type function. When BITBLT is invoked, the SI and 
DI registers are automatically saved, and automatically restored upon exit. 
Note that the BP register is always saved. 


BITBLT is passed seven double word pointers on the stack. Space will be 
allocated on the stack for eight frame variables (one structure, five bytes, 
and two words). 


The cBegin macro defines the start of the actual code. The pEzt parame- 
ter is loaded, and some values are loaded into registers. The DS and SI 
registers are saved on the following cCall. 


Another C function, “THERE”, is invoked by the cCall macro. Four argu- 
ments are passed to THERE: pDestBitmap , the 32-bit pointer in DS:SI, 
register AX, and register BX. The cCall macro places the arguments on the 
stack in the correct order. 


When THERE returns, the arguments placed on the stack are automati- 
cally removed, and the DS and SI registers are restored. 
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When cEnd is reached, the frame variables are removed, any autosave 
registers are restored, and a return of the correct type (near or far) is per- 
formed. 


Example 


cProc BITBLT,<FAR,PUBLIC>,<si,di> 


ParmD pDestBitmap ;--> to dest bitmap descriptor 
ParmD pDestOrg *--> to dest origin (a point) 
ParmD porcBitmap ;--> to source bitmap descriptor 
ParmD psrcOrg *--> to source origin 

ParmD pExt ;--> to rectangle extent 

ParmD pRop ;--> to rasterop descriptor 
ParmD pBrush ;--> to a physical brush 

LocalV nOps,4 ;# of each operand used 

LocalB phaseH ;Horizontal phase (rotate count) 
LocalB PatRow ;Current row for patterns [0O..7] 
LocalB direction ;Increment/decrement flag 
LocalW startMask smask for first dest byte 
LocalW lastMask smask for last dest byte 
LocalB Firstfetch >;Number of first fetches needed 
LocalB stepDirection ;Direction of move (left right) 
cBegin 

lds $1... pEXE 

mov ax,extentxX[si] 

mov bx,extentY[si] 


RegPtr dest,ds,si 
Save <ds,si> 


cCall THERE , <pDestBitmap,dest,ax,bx> 


mov extentX [si] ,cx 
MOV extentY[si],dx 
cEnd 
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8.1 Introduction 


Windows communicates with applications through formatted window mes- 
sages. The messages are sent to an application’s window function to let the 
function process the messages as desired. 


A message consists of three parts: a message number, a word parameter, 
and a long parameter. Message numbers are identified by predefined mes- 
sage names. The names begin with “WM_" and suggest the meaning or 
origin of the message. The word and long parameters, named wParam and 
/Param, contain values that depend on the message number. If a given 
message does not use the parameter, it is set to 0. 


The /Param parameter often contains more than one piece of information. 
For example, the high-order word may contain a handle to a window, and 
the low-order word an integer value. The HIWORD and LOWORD utility 
macros can be used to extract the high- and low-order words of [Param. 
The HIBYTE and LOBYTE utility macros can also be used with HIWORD 
and LOWORD to access any of the bytes. Casting can also be used. 


There are four ranges of message numbers, as follows: 


0—- WM_USER-1_ Reserved for use by Windows. 
WM_ USER - 7FFF (hexadecimal) 


“Integer” messages for use by applications. 


8000 — BFFF (hexadecimal) 
Reserved for use by Windows. 


C000 — FFFF (hexadecimal) 
“String” messages for use by applications. 


Message numbers in the first range (0 - WM_ USER-1) are defined by Win- 
dows and discussed in the remainder of this chapter. Values in this range 
that are not explicitly defined are reserved for future use by Windows. 


Message numbers in the second range (WM_ USER ~ 7FFF) can be defined 
and used by an application to send messages within the application. How- 
ever, these messages should not be sent to other applications unless the 
applications have agreed in advance to exchange messages and to attach 
the same meaning to the message numbers. 


Message numbers in the third range (8000 — BFFF) are reserved for future 
use by Windows. 
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Message numbers in the fourth range (C000 — FFFF) are defined when an 
application calls Register Window Message to obtain a message number 
for a string. All applications that register the identical string can use the 
associated message number for exchanging messages with each other. How- 
ever, the actual message number is not a constant and cannot be assumed 
to be the same in different window sessions. 


8.2 Window Management Messages 


This section describes the messages that Windows sends to an application 
when the state of a window changes. 
WM_ CREATE 


Purpose This message occurs when Create Window is called. It is 
sent before the Create Window call returns and before the 
window is made visible. The message informs the applica- 
tion that it can now perform any initialization desired. 


Parameters wParam is not used. 
lParam is a long pointer toa CREATESTRUCT data 
structure, whose fields correspond to the parameters passed 
to Create Window. 

WM_SETVISIBLE 


Purpose This message is sent immediately before a window is made 
visible or or hidden. 


Parameters wParam is nonzero if the window is being made visible, and 
zero if it is being made invisible. 


[Param is not used. 


WM_QUERYOPEN 


Purpose This message is sent to an icon when the user is requesting 
that it be opened into a window. Returning zero prevents 
the icon from being opened; returning nonzero permits it. 


Parameters wParam and [Param are not used. 


Default Action DefWindowProc returns nonzero. 
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WM_ ENABLE 

Purpose This message occurs after a window has been enabled or dis- 
abled. 

Parameters wParamis nonzero if the window has been enabled, and zero 
if it has been disabled. 
{Param is not used. 

WM_SETFOCUS 

Purpose This message is sent after a window gets the input focus. 

Parameters wParam contains the handle of the window losing the input 
focus (may be NULL). 
{Param is not used. 

Notes If an application wants to display a caret, it should call the 
appropriate caret functions at this point. 

WM_ KILLFOCUS 

Purpose This message is sent immediately before a window loses the 
input focus. 

Parameters wParamcontains the handle of the window receiving the 
input focus (may be NULL). 
lParam is not used. 

Notes If an application is displaying a caret, the caret should be 
destroyed at this point. 

WM_ACTIVATE 

Purpose This message occurs when a window becomes active or inac- 
tive. 

Parameters wParamspecifies the new state of the window. It is zero if 


the window is inactive. It is one of the following nonzero 
values if the window is becoming active: 
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Value Meaning 


1 The window is becoming active through 
some other method than a mouse click 
(for example, a call to SetActiveWin- 
dow or selection of the window by the 
user through the keyboard interface.) 


2 The window is becoming active because 
of a mouse click by the user. Any mouse 
button can be clicked: right, left, or mid- 
dle. 


The high-order word of (Param is nonzero if the window is 
iconic. Otherwise, it is zero. The value of the low-order 
word of [Param depends on the value of wParam. If wParam 
is zero, the low-order word of [Param is a handle to the win- 
dow becoming active. If wParam is nonzero, the low-order 
word of [Param is the handle of the window becoming inac- 


tive (this handle may be NULL). 


Default Action If the window is becoming active and it is not iconic, 


DefWindowProc sets the input focus to the window. 


WM_ACTIVATEAPP 


Purpose 


Parameters 
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This message is sent when the window that is being 
activated belongs to a different application than the window 
that previously was active. If the activation is changing to 
another window created by the same application, no 


WM_ACTIVATEAPP message is sent. 


wParam is nonzero if the window is being made active. If 
wParam is zero, the window is becoming inactive. 


If wParam is nonzero, the low-order word of [Param contains 
the task handle of the previously active application. If 
wParam is zero, the low-order word of /Param contains the 
task handle of the application being activated. 


Window Messages 


WM_ SHOW WINDOW 


Purpose This message is sent whenever a window is to be hidden or 
shown. A window is hidden or shown when one of the fol- 
lowing events occurs: 


1. Show Window is called. 
A tiled window is zoomed or “unzoomed.” 


A tiled or popup window is closed (made iconic) or 
opened (displayed on the screen). 


When a tiled window is zoomed, all popup windows not 
associated with that tiled window are hidden (that is, they 
receive a WM_SHOWWINDOW message with wParam set 
to 0). When the window is unzoomed, all hidden popup win- 
dows are shown. 


When a tiled window is closed, all popup windows associ- 
ated with the window are hidden. 


Parameters wParamis nonzero if the window is being shown, 0 if it is 
being hidden. 


[Param is 0 if the message is sent because of a Show Win- 
dow call. Otherwise, [Param is one of the following values: 


Value Meaning 

SW_ OTHERZOOM Another window is being 
zoomed. 

SW_ OTHERUNZOOM Another window is being 
unzoomed. 


SW_ PARENTCLOSING The parent window is 
closing (being made 
senthel or a popup window 
is being hidden. 


SW_ PARENTOPENING The parent window is 
opening (being displayed) 
or a popup window is 
being shown. 


Default Action DefWindowProc hides or shows the window as specified. 
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Notes 


WWM_ SIZE 


Purpose 


Parameters 


Notes 
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If an application has a hidden popup window when another 
window zooms and unzooms, the popup window will be 
shown when the window unzooms. To prevent this, the 
application should process any WM_SHOWWINDOW mes- 
sages sent to the hidden popup window instead of passing 
them directly to DefWindowProc. 


This message occurs after the size of a window has been 


changed. 


wParam contains a value defining the type of resizing 
requested. It can be one of the following: 


Value 


SIZEICONIC 
SIZEFULLSCREEN 


SIZENORMAL 


SIZEZOOMSHOW 


SIZEZOOMHIDE 


Meaning 


Window has been made iconic. 


Window has been made full- 
screen. 


Window has been resized, but 
neither SIZEICONIC nor 
SIZEFULLSCREEN applies. 


Sent to all tiled windows when 
some other window has been 
“unzoomed” back to its former 
position. 


Sent to all tiled windows when 
some other window is zooming 
to full-screen. 


[Param contains the new width and height of the client area 
of the window. The width is in the low-order word; the 
height is in the high-order word. 


If SetScrollPos or Move Window is called for a child win- 
dow as a result, of the WM_ SIZE message, the bRedraw 


parameter should be nonzero to force the window to be 


repainted. 
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WM_MOVE 

Purpose This message is sent when a window is moved. 

Parameters wParamis not used. 
{Param contains the new location of the upper left corner of 
the client area of the window. The x coordinate is in the 
low-order word and the y coordinate is in the high-order 
word. For child style windows, the location is in the client 
coordinates of the parent window. For tiled and popup style 
windows, the location is in screen coordinates. 

WM_ ERASEBKGND 

Purpose This message occurs when the window background needs 
erasing (for example, when a popup window is removed). It 
is sent in preparation for painting an invalidated region. 

Parameters wParam contains the display context handle. 


[Param is not used. 


Default Action The background is erased, using the class background brush 


specified by the hbrbackground field in the class structure. 


Return Value WM_-ERASEBKGND returns nonzero if the background is 


Notes 


WM_ PAINT 


Purpose 


erased. Otherwise, it returns zero. If the application 
processes the WM_ERASEBKGND message, it is responsi- 


ble for returning the appropriate value. 


If hbrbackground is NULL, the application is responsible for 
processing the WM_ERASEBKGND message and erasing 
the background color. When processing the 
WM_ERASEBKGND message, the application must align 
the origin of the brush it intends to use with the window 
coordinates by first calling UnrealizeObject for the brush, 
then selecting the brush. 


This message occurs whenever Windows or an application 
makes a request to repaint a portion of an application’s win- 
dow. The message is sent either when Update Window is 
called or by DispatchMessage when the application 
obtains a WM_ PAINT message using GetMessage or 

Peek Message. 
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Parameters wParam is not used. 


‘Param contains a long pointer to a data structure contain- 
ing information about the area of the screen to be painted. 


The data structure has PAINTSTRUCT type. 
Default Action None. 


WM_CTLCOLOR 


Purpose This message is sent to the parent window of a predefined 
control or message box when the control or message box is 
about to be drawn. By responding to this message, the 
parent window can set the text and background colors of 
the child window, using the display context handle given in 
the wParam parameter. 


Parameters wParamis a handle to the display context for the child win- 
dow. 


The low-order word of lParam is a handle to the child win- 
dow. The high-order word is one of the following values, 
indicating the type of control: 


Value Control Type 
CTL_ MSGBOX Message box 
CTL_ EDIT Edit control 
CTL_ LISTBOX List box control 
CTL_ BTN Button control 
CTL_ DLG Dialog box 

CTL_ SCROLLBAR Scroll bar control 
CTL_STATIC Static control 


Default Action DefWindowProc selects the default system colors. 


Notes When processing the WM_ CTLCOLOR message, the appli- 
cation must align the origin of the brush it intends to use 
with the window coordinates by first calling UnrealizeOb- 
ject for the brush, then setting the brush origin to the 
upper left corner of the window. 
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WM_ GETTEXT 


Purpose 


This message is used to copy the text corresponding to a 
window. [or edit controls, the text to be copied is the con- 
tent of the control. For button controls, the text is the but- 
ton name. For other windows, the text is the window cap- 
tion. 


Parameters wParamis an integer value specifying the maximum number 
of bytes to be copied, including the null terminator. 
[Param contains a long pointer to the buffer to receive the 
text. 

Notes This message returns the number of bytes copied. 

WM_GETTEXTLENGTH 

Purpose This message is used to find the length, in bytes, of the text 
associated with a window. The length does not include the 
null terminator. For edit controls, the text is the content of 
the control. For button controls, the text is the button 
name. For other windows, the text is the window caption. 

Parameters wParamand [Param are not used. 

Notes This message returns the length of the given text. 

WM_SETTEXT 

Purpose This message is used to set the text of a window. For edit 
controls, the text to be set is the content of the control. For 
button controls, the text is the button name. For other win- 
dows, the text is the window caption. 

Parameters wParam is not used. 
(Param contains a long pointer to a null-terminated string 
that is the window text. 

WM_SETREDRAW 

Purpose This message sets or clears the redraw flag, which deter- 


mines whether updates to a control are displayed. When the 
redraw flag is set, the control is redrawn immediately after 
each change. When the redraw flag is cleared, no redrawing 
is done. 
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lor example, this message could be sent to a list box to 
suppress update display before adding several items to the 
list, then sent again to restore update display after the 
items are added. 


Parameters If wParam is nonzero, the redraw flag is set. If wParam is 
zero, the flag is cleared. 


{Param is not used. 


WM_ GETDLGCODE 


Purpose This message is sent by the Windows dialog manager to a 
control. Normally, the dialog manager handles all arrow 
key and tab key input to the control. By responding to the 
WM_ GETDLGCODE message, an application can take con- 
trol of a particular type of input and process the input 
itself. 


Parameters wParam and lParam are not used. 


Return Value If processing the WM_GETDLGCODE message, the applica- 
tion should return one of the following values, indicating 
which type of input it will handle itself: 


Value Type of input 

DLG_ WANTARROWS Arrow keys 

DLG_ WANTTAB Tab key 

DLG_ WANTALLKEYS _ All keyboard input 
DLG_ HASSETSEL EM_SETSEL messages 


Default Action DefWindowProc returns 0. 


Notes Although DefWindowProc always returns 0 in response to 
the WM_ GETDLGCODE message, the window functions for 
the predefined control classes return a code appropriate for 
each class. 
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WM_ CLOSE 
Purpose This message occurs whenever the window Is closed. 
Parameters wParamis not used. 

[Param is not used. 


Default Action DefWindowProc calls the Destroy Window function to 
destroy the window. 


Notes An application can prompt the user for confirmation before 
destroying a window by processing the WM_ CLOSE mes- 
sage and calling Destroy Window only if the user confirms 


the choice. 
WM_ DESTROY 
Purpose This message is sent when Destroy Window is called, after 


the window has been removed from the screen. The 
WM_ DESTROY message is sent to a parent window before 
any of its child windows are destroyed. 


Parameters wParam and /lParam are not used. 


Notes If a window receiving the WM_ DESTROY message is part 
of the clipboard viewer chain (set through a call to SetClip- 
board Viewer), its first action must be to remove itself 
from the clipboard viewer chain by calling ChangeClip- 


boardChain. 
WM_ QUERYENDSESSION 
Purpose This message occurs when the user invokes the “End Ses- 


sion” command. If an application is willing to shut down, it 
should reply nonzero to this message. Otherwise, it returns 
zero. 


If any application returns zero, the session is not ended. 
Windows stops sending WM_ QUERYENDSESSION mes- 
sages as soon as one application returns zero, and sends 
WM_ENDSESSION messages with wParam set to zero to 
any applications that have already returned nonzero. 


Parameters wParam is not used. 
[Param is not used. 


Default Action DefWindowProc returns nonzero. 
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WM_ENDSESSION 


Purpose 


Parameters 


Notes 


WM_ QUIT 


Purpose 


Parameters 


This message is sent to tell an application that has 
responded nonzero to a WM_ QUERYENDSESSION mes- 


sage whether the session is actually being ended or not. 


wParam is nonzero if the session is being ended. Otherwise, 
it is zero. 


lParam is not used. 


The application does not need to call Destroy Window or 
PostQuitMessage when the session is being ended. 


This message indicates a request to terminate an applica- 

tion. It is generated by the application calling the Post- 

QuitMessage function. It causes the GetMessage func- 
tion to return zero. 


wParam contains the exit code given in the PostQuitMes- 
sage call. 


[Param is not used. 


8.3 Initialization Messages 


This section describes the window messages sent by Windows when a menu 
or dialog box is first created. 


WM_INITMENUPOPUP 


Purpose 


Parameters 
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This message is sent immediately before a popup menu is 
displayed. Processing this message allows an application to 
change the state of items on the popup menu before the 
menu is shown, without changing the state of the entire 
menu. 


wParam is the menu handle of the popup menu. 
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The low-order word of [Param is the index of the popup 
menu in the main menu. The high-order word of lParam is 
nonzero if the popup menu is the system menu. Otherwise, 
it is zero. 


Default Actton None. 
WM_INITMENU 


Purpose This message is a request to initialize a menu. It occurs 
when a user moves the mouse cursor into a menu bar and 
presses a mouse button, or presses a menu key. Windows 
sends the message before displaying the menu. This lets the 
application change the state of menu items, if desired, 
before the menu is shown. 


Parameters wParam is the menu handle of the menu to be initialized. 
[Param is not used. 
Default Action None. 


Notes A WM_INITMENU message is sent only when a menu is 
first accessed and only one WM_INITMENU is generated 
for each access. This means, for example, that dragging the 
mouse across several menu items while holding down the 
button does not generate new messages. The message does 
not provide information about menu items. 


WM_INITDIALOG 


Purpose This message is sent immediately before a dialog box is 
displayed. Processing this message allows an application to 
perform any initialization desired before the dialog box is 
made visible. 


Parameters wParamcontains a handle to the first control item in the 
dialog box that can be given the input focus. (Generally, 
this is the first item in the dialog box with WS_ TABSTOP 
style). If the application returns a nonzero value in response 
to the WM_INITDIALOG message, Windows sets the input 


focus to the item given by wParam. 


[Param is not used. 


Notes When an application receives the WM_INITDIALOG mes- 
sage in a dialog box function, it can request that Windows 
set the input focus to the control given in wParam by 
returning nonzero. Returning zero tells Windows NOT to set 
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the focus; in this case, the dialog box function should set the 
input focus itself by calling SetFocus while processing the 


WM_INITDIALOG message. 


If necessary, an application can call EndDialog during the 


processing of the WM_INITDIALOG message. 


8.4 Input Messages 


The messages in this section are sent when an application receives input 
through the mouse, keyboard, scroll bars, or system timer. 


WM_MOUSEMOVE 
Purpose ‘This message occurs when the user moves the mouse. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 
lowing: 


Value Meaning 


MK LBUTTON _ Set if left button is down. 

MK-—RBUTTON _ Set if right button is down. 

MK_MBUTTON _ Set if middle button is down. 

MkK_ SHIFT Set if SHIFT key is down. 

MK CONTROL — Set if CONTROL key is down. 
{Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 


coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Action None. 


Notes The MAKEPOINT macro can be used to convert the /Param 
parameter to a POINT. 


364 


Window Messages 


WM_LBUTTONDOWN 


Purpose 


This message occurs when the user presses the left mouse 
button. 


Parameters wParamcontains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 
lowing: 

Value Meaning 

MK-RBUTTON — Set if right button is down. 

MK—_MBUTTON — Set if middle button is down. 

MK_ SHIFT Set if SHIFT key is down. 

MK CONTROL — Set if CONTROL key is down. 
(Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 

Default Action None. 

WM_LBUTTONUP 

Purpose This message occurs when the user releases the left mouse 
button. 

Parameters wParamcontains a value indicating whether or not various 


virtual keys are down. It can be any combination of the fol- 
lowing: 


Value Meaning 


MK-RBUTTON _ Set if right button is down. 
MK MBUTTON _ Set if middle button is down. 
MkK~— SHIFT Set if SHIFT key is down. 
MK CONTROL — Set if CONTROL key is down. 
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/Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Action None. 
WM_RBUTTONDOWN 


Purpose This message occurs when the user presses the right mouse 


button. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 


lowing: 
Value 


MK— LBUTTON 
MK— MBUTTON 
MkK— SHIFT 
MK_~ CONTROL 


Meaning 


Set if left button is down. 

Set if middle button is down. 
Set if SHIFT key is down. 

Set if CONTROL key is down. 


(Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Action None. 
WM_RBUTTONUP 


Purpose This message occurs when the user releases the right mouse 


button. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 


lowing: 
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Value 


MK_ LBUTTON 
MK~ MBUTTON 
MK~— SHIFT 
MK—~ CONTROL 
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Meaning 


Set if left button is down. 

Set if middle button is down. 
set if SHIFT key is down. 

Set if CONTROL key is down. 


[Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Action None. 
WM_MBUTTONDOWN 


Purpose This message occurs when the user presses the middle mouse 


button. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 


lowing: 
Value 


MK_~ LBUTTON 
MK_— RBUTTON 
MK~— SHIFT 

MK_ CONTROL 


Meaning 


Set if left button is down. 

Set if right button is down. 
Set if SHIFT key is down. 

set if CONTROL key is down. 


(Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Action None. 
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WM_MBUTTONUP 


Purpose 


This message occurs when the user releases the middle 
mouse button. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 
lowing: 

Value Meaning 

MK_LBUTTON — Set if left button is down. 

MK_RBUTTON — Set if right button is down. 

MK_ SHIFT Set if SHIFT key is down. 

MK CONTROL — Set if CONTROL key is down. 
lParam contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 

Default Action None. 

WM_LBUTTONDBLCLK 

Purpose This message occurs when the user double clicks the left 
mouse button. 

Parameters wParam contains a value indicating whether or not various 
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virtual keys are down. It can be any combination of the fol- 
lowing: 


Value Meaning 


MK_LBUTTON _ Set if left button is down. 
MK_RBUTTON — Set if right button is down. 
MK-MBUTTON _ Set if middle button is down. 
MK_— SHIFT Set if SHIFT key is down. 
MK CONTROL — Set if CONTROL key is down. 


[Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 
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Default Action None. 
Notes Only windows whose window class has the CS_ DBLCLKS 


style can receive double click messages. Windows generates 
a double click message whenever the user presses, releases, 
and then presses a mouse button again within the system’s 
double click time limit. Double clicking actually generates 
four messages: a down click message, an up click message, 
the double click message, and another up click message. 


WM_RBUTTONDBLCLK 


Purpose This message occurs when the user double clicks the right 
mouse button. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 
lowing: 


Value Meaning 


MK_LBUTTON — Set if left button is down. 
MK_RBUTTON © Set if right button is down. 
MK~— SHIFT Set if SHIFT key is down. 
MK CONTROL — Set if CONTROL key is down. 


{Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Actton None. 
Notes Only windows whose window class has the CS_ DBLCLKS 


style can receive double click messages. Windows generates 
a double click message whenever the user presses, releases, 
and then presses a mouse button again within the system’s 
double click time limit. Double clicking actually generates 
three messages: a down click message, an up click message, 
and finally the double click message. 
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WM_MBUTTONDBLCLK 


Purpose This message occurs when the user double clicks the middle 


mouse button. 


Parameters wParam contains a value indicating whether or not various 
virtual keys are down. It can be any combination of the fol- 


lowing: 
Value 


MK_ LBUTTON 
MK— RBUTTON 
MK— MBUTTON 
MK_ SHIFT 

MK~ CONTROL 


Meaning 


Set if left button is down. 

set if right button is down. 
Set if middle button is down. 
set if SHIFT key is down. 

Set if CONTROL key is down. 


[Param contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Action None. 


Notes Only windows whose window class has the CS_ DBLCLKS 
style can receive double click messages. Windows generates 
a double click message whenever the user presses, releases, 
and then presses a mouse button again within the system’s 
double click time limit. Double clicking actually generates 
four messages: a down click message, an up click message, 
the double click message, and another up click message. 


WM_KEYDOWN 


Purpose This message is sent when a non-system key is pressed. 


Parameters wParamis an integer value specifying the virtual key code of 


the given key. 


‘Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 
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Bit Value 


1-16 Repeat count (the number of times the 
keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OKM-dependent value). 

29 Context code (1 if ALT key was held down 
while key was pressed, 0 otherwise.) 

30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). 

31 Transition state (1 if key is being released, 


0 if key is being pressed). 


For WM_KEYDOWN messages, the key transition bit (bit 
31) is 0 and the context code (bit 29) is 0. 


A system key message occurs when any key is pressed while 
the ALT key is held down or while no window has the input 
focus; a non-system key message occurs when a key is 
pressed in any other circumstances. 


Because of auto-repeat, more than one WM_KEYDOWN 
message may occur before a WM_KEYUP message is sent. 
The previous key state (bit 30) can be used to determine 
whether the WM_KEYDOWN message indicates the first 


down transition or a repeated down transition. 


WM_KEYUP 


Purpose 


Parameters 


This message is sent when a non-system key is released. 


wParam is an integer value specifying the virtual key code of 
the given key. 


[Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 
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Bit Value 


1-16 Repeat count (the number of times the 
keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OEM-dependent value). 

29 Context code (1 if ALT key was held down 
while key was pressed, 0 otherwise. ) 

30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). 

31 Transition state (1 if key is being released, 


0 if key is being pressed). 
For WM_KEYUP messages, the key transition bit (bit 31) is 
1 and the context code (bit 29) is 0. 


Notes A system key message occurs when any key is pressed while 
the ALT key is held down or while no window has the input 
focus; a non-system key message occurs when a key is 
pressed in any other circumstances. 


WM_ CHAR 


Purpose This message is the result of a translated WM_KEYUP or 
WM_KEYDOWN message. It contains the ASCII value of 
the keyboard key being pressed or released. 


Parameters wParam contains the ASCII value of the key. 


{Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 


Bit Value 
1-16 Repeat count (the number of times the 


keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OEM-dependent value). 
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29 Context code (1 if ALT key was held down 
while key was pressed, 0 otherwise. ) 

30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). 

31 Transition state (1 if key is being released, 
0 if key is being pressed). 

Default Action None. 
Notes Since there is not necessarily a one-to-one correspondence 


between keys pressed and character messages generated, the 
information in the high-order word of /Param is not gen- 
erally useful to applications. The information applies only 


to the most recent WM_KEYUP or WM_KEYDOWN mes- 


sage before the character message was posted. 


WM_ DEADCHAR 


Purpose 


Parameters 


This message is the result of a translated WM_KEYUP or 
WM_KEYDOWN message. It specifies the character value 
of a dead key. A dead key is a key such as the umlaut (dou- 
ble dot) character that is combined with other characters to 
form a composite character. For example, the umlaut-O 
character consists of the dead key, umlaut, and the “O” key. 


wParam contains the dead key character value. 


[Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 


Bit Value 
1-16 Repeat count (the number of times the 


keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OEM-dependent value). 
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29 1 if ALT key was held down while key was 
pressed, 0 otherwise. 

30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). 

31 Transition state (1 if key is being released, 
0 if key is being pressed). 

Default Action None. 
Notes The WM_ DEADCHAR message is typically used by applica- 


tions that want to give the user feedback about each key 
pressed. 


Since there is not necessarily a one-to-one correspondence 
between keys pressed and character messages generated, the 
information in the high-order word of lParam is not gen- 
erally useful to applications. The information applies only 


to the most recent WM_KEYUP or WM_KEYDOWN mes- 


sage before the character message was posted. 


WM_ TIMER 


Purpose 


Parameters 


This message occurs when the time limit set for a given 
timer has elapsed. 


wParam contains the timer ID, an integer value that 
uniquely identifies the timer. 


[Param contains the long pointer to a function that was 
passed to Set Timer when the timer was created. If lParam 
is not NULL, the specified function is called directly, instead 
of sending the WM_ TIMER message to the window func- 


tion. 


Default Action None. 


WM_ COMMAND 


Purpose 


Parameters 
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This message occurs when the user selects an item from a 
menu, when a control passes a message to its parent win- 
dow, or when an accelerator keystroke is translated. 


wParam contains either the menu item, the control ID, or 
the accelerator ID. 


[Param contains 0 if the message is from a menu. If the 
message is an accelerator message, the high-order word of 
(Param is 1. If the message is from a control, the high-order 
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word of /Param contains the window handle of the control 
sending the message and the low-order word contains the 
control [D. 


Notes Accelerator keystrokes that are defined to select items from 


the system menu are translated into WM_SYSCOMMAND 


messages. 


If an accelerator keystroke corresponding to a menu item 
occurs when the window owning the menu Is iconic, no 
WM_ COMMAND message is sent. However, if an accelera- 
tor keystroke occurs that does not match any of the items 
on the window’s menu or on the system menu, a 


WM_ COMMAND message is sent, even if the window is 


iconic. 
WM_VSCROLL 
Purpose This message occurs whenever the user clicks the mouse on 


the vertical scroll bar. 


Parameters wParamcontains a scroll bar code specifying the user’s scrol- 
ling request. It can be any one of the following: 


Value Meaning 

SB_ LINEUP Scroll one line up. 
SB_ LINEDOWN Scroll one line down. 
SB_ PAGEUP Scroll one page up. 
SB_ PAGEDOWN Scroll one page down. 


SB_ THUMBPOSITION Scroll to absolute position. 
SB_ THUMBTRACK Thumb is being dragged and is 


current at the specified posi- 


tion. 
SB_ TOP Scroll to top. 
SB_ BOTTOM Scroll to bottom. 
SB_ ENDSCROLL End of scroll. 


(Param contains the current position of the thumb if 
wParam is either SB_- THUMBPOSITION or 
SB_-THUMBTRACK. Otherwise, /Param is not used. The 
thumb position, when given, is in the low-order word of 
lParam. 
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Notes 


The SB_ THUMBTRACK message is typically used by appli- 
cations that give some feedback while the thumb is being 
dragged. 


If an application scrolls the document in the window, it 
must also reset the position of the thumb by using the 
SetScrollPos function. 


WM_ HSCROLL 


Purpose 


Parameters 


Notes 
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This message occurs whenever the user clicks the mouse on 
the horizontal scroll bar. 


wParam contains a scroll bar code specifying the user’s scrol- 
ling request. It can be any one of the following: 


Value Meaning 


SB_ LINEUP Scroll one line left. 

SB_ LINEDOWN Scroll one line right. 

SB_ PAGEUP Scroll one page left. 

SB_ PAGEDOWN Scroll one page right. 
SB_THUMBPOSITION Scroll to absolute position. 


SB_ THUMBTRACK Thumb is being dragged and is 
currently at the specified posi- 
tion. 


SB_ TOP Scroll to far left. 
SB_ BOTTOM Scroll to far right. 
SB_ ENDSCROLL End of scroll. 


[Param contains the current position of the thumb if 
wParam is either SB_ THUMBPOSITION or 

SB_ THUMBTRACK. Otherwise, /Param is not used. The 
thumb position, when given, is in the low-order word of 
lParam. 


The SB_ THUMBTRACK message is typically used by appli- 
cations that give some feedback while the thumb is being 
dragged. 


If an application scrolls the document in the window, it 
must also reset the position of the thumb by using the 
SetScrollPos function. 


Window Messages 


8.5 System Messages 


This section describes messages that Windows sends to an application when 
a user accesses a window’s system menu, scroll bars, or size box. Although 
an application can process these messages, if desired, most applications 
pass them to the DefWindowProc function for default processing. 


WM_SYSKEYDOWN 


Purpose This message occurs whenever the user holds down the ALT 
key and then presses another key. It also occurs when no 
window currently has the input focus; in this case, the 
WM_SYSKEYDOWN message is sent to the active window. 
The window receiving the message can distinguish between 
these two contexts by checking the context code in /Param. 


Parameters wParam contains the virtual key code of the key being 
pressed. 


‘Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 


Bit Value 
1-16 Repeat count (the number of times the 


keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OEM-dependent value). 

29 Context code (1 if ALT key was held down 
while key was pressed, 0 otherwise.) 

30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). | 

31 Transition state (1 if key is being released, 


0 if key is being pressed). 


For WM_SYSKEYDOWN messages, the key transition bit 
(bit 31) is 0. The context code (bit 29) is 1 if the ALT key 
was down while the key was pressed, and is 0 if the message 
was sent to the active window because no window has the 
input focus. 
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Notes When the context code is zero, the message can be passed to 
TranslateAccelerator, which will handle it as though it 
were a normal key message instead of a system key message. 
This allows accelerator keys to be used with the active win- 
dow even if the active window doesn’t have the focus. 


Because of auto-repeat, more than one 
WM_SYSKEYDOWN message may occur before a 
WM_SYSKEYUP message is sent. The previous key state 
bit 30) can be used to determine whether the 
SYSKEYDOWN message indicates the first down tran- 


sition or a repeated down transition. 


WM_SYSKEYUP 


Purpose This message occurs whenever the user releases a key that 
was pressed while the ALT key was held down. It also 
occurs when no window currently has the input focus; in this 
case, the WM_SYSKEYUP message is sent to the active 
window. The window receiving the message can distinguish 
between these two contexts by checking the context code in 
(Param. 


Parameters wParam contains the virtual key code of the key being 
released. 


(Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 


Bit Value 
1-16 Repeat count (the number of times the 


keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OEM-dependent value). 

29 Context code (1 if ALT key was held down 
while key was pressed, 0 otherwise.) 

30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). 

31 Transition state (1 if key is being released, 


0 if key is being pressed). 


For WM_SYSKEYUP messages, the key transition bit (bit 
31) is 1. The context code (bit 29) is 1 if the ALT key was 
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down while the key was pressed, and is 0 if the message was 
sent to the active window because no window has the input 
focus. 


When the context code is zero, the message can be passed to 
TranslateAccelerator, which will handle it as though it 
were a normal key message instead of a system key message. 
This allows accelerator keys to be used with the active win- 
dow even if the active window doesn’t have the focus. 


WM_SYSCHAR 


Purpose 


Parameters 


Notes 


This message is the result of translating a WM_SYSKEYUP 
or WM_SYSKEYDOWN message. It specifies the virtual 
key code of the system menu key. 


wParam contains the virtual key code of a system menu key. 


‘Param contains the repeat count, scan code, key transition 
code, previous key state, and context code, as shown below. 
In the following list, bit 1 is the low-order bit. 


Bit Value 


1-16 Repeat count (the number of times the 
keystroke is repeated as a result of the user 
holding down the key.) 


17-25 Scan code (OEM-dependent value). 


29 Context code (1 if ALT key was held down 
while key was pressed, 0 otherwise.) 


30 Previous key state (1 if key was down 
before the message was sent, 0 if key was 
up). 

31 Transition state (1 if key is being released, 
0 if key is being pressed). 


When the context code is zero, the message can be passed to 
TranslateAccelerator, which will handle it as though it 
were a normal key message instead of a system key message. 
This allows accelerator keys to be used with the active win- 
dow even if the active window doesn’t have the focus. 


Default Action None. 
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WM_SYSDEADCHAR 

Purpose This message is the result of a translated WM_SYSKEYUP 
or WM_SYSKEYDOWN message. It specifies the character 
value of a dead key. 

Parameters wParam contains the dead key character value. 
[Param contains a repeat count and an auto-repeat count. 
The low-order word contains the repeat count; the high- 
order word contains the auto-repeat count. 

Default Action None. 

WM_SYSCOMMAND 

Purpose This message occurs when the user selects a command from 
the system menu. 

Parameters wParamis an integer value specifying the type of system 
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command requested. It can be any one of the following: 


Value Meaning 

SC_ SIZE Request to size the window 

SC_ MOVE Request to move the window 

SC_ICON Request to make the window 
iconic 

SC_ ZOOM Request to zoom the window 

SC_ CLOSE Request to close the window 


SC_ NEXTWINDOW 


Request to move to the next 
window 


SC_ PREVWINDOW 


Request to move to the previ- 
ous window 


SC_ VSCROLL 


Request for a vertical scroll 


SC_ HSCROLL 
SC_ MOUSEMENU 


SC_ KE YMENU 


lParam is not used. 


Request for a horizontal scroll 


Request for a menu through a 
mouse click 


Request for a menu through a 
keystroke 
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Default Action DefWindowProc carries out the system menu request for 


Notes 


the predefined actions specified above. 


In WM_SYSCOMMAND messages, the four low-order bits 
of wParam are used internally by Windows. When an appli- 
cation tests the value of wParam, it must combine the value 
FF FO (hexadecimal) with the wParam value, using the bit- 
wise AND operator, to obtain the correct result. 


The menu items in a system menu can be modified by using 
the GetSystemMenu and ChangeMenu functions. Appli- 
cations that modify the system menu must process 
WM_SYSCOMMAND messages. Any 
WM_SYSCOMMAND messages not handled by the applica- 
tion must be passed to DefWindowProc. Any command 
values added by an application must be processed by the 
application and cannot be passed to DefWindowProc. 


An application can carry out any system command at any 
time by passing a WM_SYSCOMMAND message to 
DefWindowProc. 


Accelerator keystrokes that are defined to select items from 
the system menu are translated into WM_SYSCOMMAND 
messages; all other accelerator keystrokes are translated 


into WM_ COMMAND messages. 


8.6 Clipboard Messages 


This section describes messages that an application may receive from appli- 
cations trying to access the Windows clipboard. 


WM_RENDERFORMAT 


Purpose 


This message is a request to the clipboard owner to format 
the data last copied to the clipboard in the specified format 
and to pass a handle to the formatted data to the clipboard. 
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Parameters wParamspecifies the data format. It can be any one of the 
formats described with the SetClipboardData function. 


lParam is not used. 


Default Action None. 
WM_RENDERALLFORMATS 


Purpose This message is sent to the application that owns the clip- 
board when the application is being destroyed. The applica- 
tion should render the clipboard data in all formats it is 
capable of generating and pass a handle to each format to 
SetClipboardData. This ensures that the data in the clip- 
board can be rendered even though the application has been 
destroyed. 


WM_ DESTROYCLIPBOARD 


Purpose This message is sent to the clipboard owner when the clip- 
board is emptied through a call to Empty Clipboard. 


Parameters wParam and [Param are not used. 


WM_DRAWCLIPBOARD 


Purpose This message is sent to the first window in the clipboard 
viewer chain whenever the contents of the clipboard change. 
Only applications that have joined the clipboard viewer 
chain by calling SetClipboard Viewer need to process this 
message. 


Parameters wParam and [Param are not used. 


Notes Fach window receiving the WM_DRAWCLIPBOARD mes- 
sage is responsible for calling SendMessage to pass on the 
message to the next window in the clipboard viewer chain. 
The handle of the next window is returned by SetClip- 
board Viewer; it may be modified in response to a 


WM_ CHANGECBCHAIN message. 
WM_ CHANGECBCHAIN 


Purpose This message notifies the first window in the clipboard 
viewer chain that a window is being removed from the clip- 
board viewer chain. 
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Notes 
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wParam contains the handle to the window being removed 
from the clipboard viewer chain. 


The low-order word of lParam contains the handle to the 
window following the window being removed in the clip- 
board viewer chain. 


Each window receiving the WM_ CHANGECBCHAIN mes- 
sage is responsible for calling SendMessage to pass on the 
message to the next window in the clipboard viewer chain. 

If the window being removed is the next window in the 
chain, the window specified by the low-order word of lParam 
becomes the next window, and clipboard messages should be 
passed on to it. 


WM_ PAINTCLIPBOARD 


Purpose 


Parameters 


Notes 


This message is sent when the clipboard contains a data 
handle for the CF_ OWNEIERDISPLAY format ern the clip- 
board owner is responsible for displaying the clipboard con- 
tents) and the clipboard application’s client area needs 
repainting. —The WM_PAINTCLIPBOARD message is sent 
to the owner of the clipboard to request repainting of all or 
part of the clipboard application’s client area. 


wParam is a handle to the clipboard application window. 


lParam is a long pointer toa PAINTSTRUCT data struc- 
ture defining what part of the client area to paint. 


To determine whether the entire client area needs repainting 
or just a portion of it, the clipboard owner must compare 
the dimensions of the drawing area given in the rcpaint 
field of the PAINTSTRUCT structure to the dimensions 
given in the most recent WM_SIZECLIPBOARD message. 


WM_ SIZECLIPBOARD 


Purpose 


Parameters 


This message is sent when the clipboard contains a data 
handle for the CF_OWNERDISPLAY format Sac the clip- 
board owner is responsible for displaying the clipboard con- 
tents) and the clipboard application window has changed 
size. 


wParam is a handle to the clipboard application window. 
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Notes 


The low-order word of [Param is a pointer to a RECT data 
structure specifying the area in which the clipboard owner 
should paint. The high-order word is not used. 


A WM_SIZECLIPBOARD message is sent with a null rect- 
angle (0,0,0,0) as the new size when the clipboard applica- 
tion is about to be destroyed or made iconic. This permits 
the clipboard owner to free its display resources. 


WM_ VSCROLLCLIPBOARD 


Purpose 


Parameters 


Notes 
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This message is sent when the clipboard contains a data 
handle for the CF_OWNERDISPLAY format back the clip- 
board owner is responsible for displaying the clipboard con- 
tents) and an event occurs in the clipboard application’s 
vertical scroll bar. 


wParam contains a handle to the clipboard application 
window. 


The low-order word of [Param contains one of the following 
scroll bar codes: 


Value Meaning 

SB_ LINEUP Scroll one line up 

SB_ LINEDOWN Scroll one line down 

SB_ PAGEUP Scroll one page up 

SB_ PAGEDOWN Scroll one page down 

SB. THUMBPOSITION Scroll to absolute position 
SB_ TOP Scroll to top 

SB_ BOTTOM Scroll to bottom 

SB_ ENDSCROLL End of scroll 


The high-order word of [Param contains the thumb position 
if the scroll bar code is SB_ THUMBPOSITION. Otherwise, 


the high-order word is not used. 


The clipboard owner should use InvalidateRect or repaint 
as desired. The scroll bar position should also be reset. 
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WM_ HSCROLLCLIPBOARD 


Purpose 


Parameters 


Notes 


This message is sent when the clipboard contains a data 
handle for the CF_OWNERDISPLAY format Hits the clip- 
board owner is responsible for displaying the clipboard con- 
tents) and an event occurs in the clipboard application’s 
horizontal scroll bar. 


wParam contains a handle to the clipboard application 
window. 


The low-order word of [Param contains one of the following 
scroll bar codes: 


Value Meaning 

SB_ LINEUP Scroll one line left 

SB_ LINEDOWN Scroll one line right 

SB_ PAGEUP Scroll one page left 

SB_ PAGEDOWN Scroll one page right 
SB_THUMBPOSITION Scroll to absolute position 
SB_ TOP Scroll to far left 

SB_ BOTTOM Scroll to far right 

SB_ ENDSCROLL End of scroll 


The high-order word of [Param contains the thumb position 
if the scroll bar code is SB_ THUMBPOSITION. Otherwise, 


the high-order word is not used. 


The clipboard owner should use InvalidateRect or repaint 
as desired. The scroll bar position should also be reset. 


WM_ASKCBFORMATNAME 


Purpose 


Parameters 


This message is sent when the clipboard contains a data 
handle for the CF_ OWNERDISPLAY format en the clip- 
board owner is responsible for displaying the clipboard con- 
tents) to request a copy of the format name. 


wParam contains an integer value specifying the maximum 
number of bytes to copy. 


‘Param is a long pointer to the buffer where the copy of the 
format name is to be stored. 
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Notes The clipboard owner should copy the name of the 
CF_ OWNERDISPLAY type into the specified buffer, not 


exceeding the maximum number of bytes. 


8.7 System Information Messages 


The messages described in this section are sent when an application or the 
user makes a system-wide change that may affect other applications. 
WM_SYSCOLORCHANGE 


Purpose This message is sent to all top-level windows when a change 
is made in the system color setting. 


Parameters wParam and lParam are not used. 


Default Actton Portions of the screen that are affected by the system color 
changes will receive WM_ PAINT messages. 


Notes If an application has brushes corresponding to the system 
colors, it should query the system for the new system colors 
and then recreate the brushes when this message is received. 


WM_ DEVMODECHANGE 


Purpose This message is sent to all top-level windows whenever the 
user changes device mode settings. 


Parameters wParam is not used 


[Param is a long pointer to the device name as specified in 


the WIN.INI file. 
Default Action None. 


WM_ FONTCHANGE 


Purpose This message occurs when the pool of font resources 
changes. Any application that adds or removes fonts from 
the system (for example, through AddFontResource or 
RemoveF ontResource) is responsible for sending this 
message to all top-level windows. 


Parameters wParam and lParam are not used. 
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Default Action None. 
Notes To send the WM_ FONTCHANGE message to all top-level 


windows, an application can call SendMessage with the 
hWnd parameter set to FFFF (hexadecimal). 


WM_ TIMECHANGE 


Purpose This message occurs when an application makes a change (or 
set of changes) to the system time. Any application that 
changes the system time is responsible for sending this mes- 
sage to all top-level windows. 


Parameters  wParamand [Param are not used. 
Default Action None. 
Notes To send the WM_ TIMECHANGE message to all top-level 


windows, an application can use SendMessage with the 
hWnd parameter set to FFFF (hexadecimal). 


WM_ WININICHANGE 


Purpose This message occurs when the Windows initialization file 
WIN.INI) changes. Any application that makes a change to 
IN.INI is responsible for sending this message to all top- 
level windows. 


Parameters wParam is not used. 


(Param contains a long pointer to a string specifying the 
name of the section that has changed (not including the 
square brackets). If more than one section has changed, 
[Param is zero, and the application receiving the message 
must find and handle the changes itself. 


Default Action None. 
Notes To send the WM_ WININICHANGE message to all top-level 


windows, an application can use SendMessage with the 
hWnd parameter set to FFFF (hexadecimal). 
WM_SYSTEMERROR 


Purpose This message is sent to all top-level windows when an out- 
of-memory system error occurs. 


Parameters  wParamis the value 8, indicating an MS-DOS out-of- 
memory error. 


lParam is not used. 
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Default Action The MS-DOS Executive window alerts the user to the out- 
of-memory condition. 


Notes Applications do not need to process this message, since the 
out-of-memory condition is handled by the MS-DOS Execu- 
tive. 


8.8 Control Messages 


Control messages are predefined window messages that direct a control to 
carry out a specified task. Applications send control messages to a control 
using the SendMessage function. The control carries out the specified 
task and returns a value indicating the result. The following sections 
describe the control messages for each control class. 


Note 


There are no predefined scroll bar control messages. Instead, the scroll 
bar controls use the same notification messages as scroll bars that are 
not controls, except that they notify their parent. 


There are no static control messages. 


8.8.1 Button Control Messages 


This section describes messages that an application can send to a button 
control. 


BM_ GETCHECK 


Purpose This message determines whether a radio button or check 
box is checked. 


Parameters wParam and [Param are not used. 


Return Value BM_GETCHECK returns nonzero if the radio button or 
check box is checked. Otherwise, BM- GETCHECK returns 


zero. It always returns zero for a push button. 
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BM_GETSTATE 


Purpose 


Parameters 
Return Value 


This message returns nonzero if the cursor is over the button 
and the the user is pressing a mouse button or the space 
bar. 


wParam and lParam are not used. 


BM_ GETCHECK returns nonzero if the cursor is over the 
button and the user is pressing a mouse button or the space 
bar. Otherwise, BM- GETCHECK returns zero. For push 
buttons, it returns nonzero if the button is highlighted and 
zero if not. 


BM_SETCHECK 


Purpose 


Parameters 


Return Value 
Notes 


This message checks or unchecks a radio button or check 
box. 


If wParam is nonzero, a check is placed beside the button or 
box. If zero, the check (if any) is removed. For 3-state but- 
tons, if wParam is 1, a check is placed beside the button. If 
wParam is 1, the button is grayed. If wParam is 0, the but- 
ton is returned to its normal state (no checkmark or gray- 
ing). 

[Param is not used. 

None. 


BM_ SETCHECK has no effect on push buttons. 


BM_SETSTATE 


Purpose 


Parameters 


Return Value 
Notes 


This message highlights a button or check box. 


If wParam is nonzero, a black frame is drawn around the 
button, or the check box is emboldened. If zero, the 
highlight is removed. 


None. 
Push buttons cannot be highlighted. 
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8.8.2 Edit Control Messages 


This section describes the messages that an application can send to an edit 
control. In addition to the messages described below, the WM_SETFOCUS, 
WM_ KILLFOCUS, WM_SETTEXT, WM_ GETTEXT, 

WM_ GETTEXTLENGTH, WM_SETREDRAW, and WM_ ENABLE win- 


dow messages can also be used. 


EM_ GETSEL 


Purpose This message returns the starting and ending character posi- 
tions of the current selection. 


Parameters wParam and lParam are not used. 


Return Value The long value returned contains the starting position in the 
low-order word. The high-order word contains the position 
of the first non-selected character after the end of the selec- 


tion. 
EM_SETSEL 
Purpose This message selects all characters in the current text that 


are within the starting and ending character positions given 
by the /Param parameter. 


Parameters wParam is not used. 


{Param contains the starting position in the low-order word, 
and the ending position in the high-order word. The posi- 
tion values 0 to 32767 select the entire string. 


Return Value None. 


EM_ GETRECT 
Purpose This message retrieves the formatting rectangle of the con- 
trol. 


Parameters wParam is not used. 


lParam must be a long pointer to a data structure with 
RECT type. The control copies the dimensions to the 
structure. 


Return Value None. 
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BKM_SETRECT 


Purpose 


Parameters 


Return Value 
Notes 


This message sets the formatting rectangle for a control. 
The text is reformatted and redisplayed to reflect the 
changed rectangle. 


wParam is not used. 


{Param must be a data structure with RECT type specify- 
ing the new dimensions of the rectangle. 


None. 


This message will not be processed by single line edit con- 
trols. 


EM_SETRECTNP 


Purpose 


Parameters 


Return Value 
Notes 


This message is the same as EM_SETRECT, except that the 
control is NOT repainted. Any subsequent repaints cause 
the control to be repainted to reflect the changed formatting 
rectangle. This message is used when the field is to be 
repainted later. 


wParam is not used. 


{Param must be a data structure having RECT type speci- 
fying the new dimensions of the rectangle. 


None. 


This message will not be processed by single line edit con- 
trols. 


KM_SETHANDLE 


Purpose 


Parameters 


This message establishes the text buffer used to hold the 
contents of the control window. 


wParam contains a handle to the buffer. The handle must 
be a local handle to a location in the application’s data seg- 
ment (DS). The edit control uses this buffer to store the 
currently displayed text instead of allocating its own buffer. 
If necessary, the control reallocates this buffer. 


lParam is not used. 
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Return Value None. 


Notes This message will not be processed by single line edit con- 
trols. 

EM_ GETHANDLE 

Purpose This message returns the data handle of the buffer used to 
hold the contents of the control window. The handle is 
always a local handle to a location in the application’s data 
segment. 

Parameters  wParamand [Param are not used. 


Return Value 
Notes 


None. 


This message will not be processed by single line edit con- 
trols. 


EM_ GETLINECOUNT 


Purpose 


Parameters 
Return Value 


This message returns the number of lines of text in the edit 
control. 


wParam and [Param are not used. 


EM_ GETLINECOUNT returns the number of lines of text 


in the control. 


Notes This message will not be processed by single line edit con- 
trols. 

EM_ LINEINDEX 

Purpose This message returns the number of character positions that 
occur before the first character in a given line. 

Parameters wParam contains the desired line number, where the first 


line number is 0. If wParam is -1, the current line (the line 
containing the caret) is used. 


lParam is not used. 


Return Value The return value is the number of character positions before 


Notes 


892 


the first character in the line. 


This message will not be processed by single line edit con- 
trols. 
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BEM_ LINESCROLL 


Purpose 


Parameters 


Return Value 
Notes 


This message scrolls the context of the control by the given 
number of lines. 


wParam is not used. 


The high-order word of [Param contains the number of lines, 
and the low-order word contains the number of character 
positions to scroll horizontally. 


None. 


This message will not be processed by single line edit con- 
trols. 


EM_ SCROLL 


Purpose 


Parameters 


This message directs the edit control to scroll the contents 
of its window vertically. 


wParam is one of the following values: 


Value Meaning 

SB_ LINEUP Scroll one line up. 

SB_ LINEDOWN Scroll one line down. 

SB_ PAGEUP. Scroll one page up. 

SB_ PAGEDOWN Scroll one page down. 

SB_ THUMBPOSITION Scroll to thumb position. 

EM_ GETTHUMB ean the current thumb posi- 
ion. 


lParam is not used. 


Return Value If wParam is EM_GETTHUMB, the control returns the 


Notes 


current thumb position. 


This message will not be processed by single line edit con- 
trols. 
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EBEM_ LINELENGTH 


Purpose This message returns the length of a line (in bytes) in the 
edit control’s text buffer. 


Parameters wParamis the line number of the desired line, where the line 
number of the first line is 0. If wParam is —-1, the length of 
the current line (the line containing the caret) is returned, 
not including the length of any selected text. If the current 
selection spans more than one line, the total length of the 
lines minus the length of the selected text is returned. 


{Param is not used. 
Return Value EM_LINELENGTH returns the length of the given line (or 


lines). 
EM_ REPLACESEL 
Purpose This message replaces the current selection with new text. 


Parameters wParam is not used. 


[Param is a far pointer to a null-terminated string of 
replacement text. 


Return Value None. 


EM_SETFONT 

Purpose This message sets the edit control font. 

Parameters wParamis the font ID. The font must be a fixed-pitch font. 
‘Param is not used. 


Return Value None. 


EM_ GETLINE 
Purpose This message copies a line from the edit control. 


Parameters wParam contains the line number of the line in the control, 
where the line number of the first line is 0. 
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‘Param contains a far pointer to the buffer where the line 
will be stored. The first word of the buffer specifies the max- 
imum number of bytes to be copied to the buffer. The 
copied line is not null-terminated. 


Return Value The return value is the number of bytes actually copied. 


EM_ LIMIT TEXT 


Purpose 


Parameters 


Return Value 
Notes 


EM_ UNDO 


Purpose 


Parameters 


This message limits the length (in bytes) of the text the user 
may enter. 


wParam specifies the maximum number of bytes that can be 
entered. If the user attempts to enter more characters, the 
edit control beeps and does not accept the characters. If 
wParam is 0, no limit is imposed on the size of the text 
(until no more memory is available). 


lParam is not used. 


None. 


EM_ LIMITTEXT does not affect text set by 
WM_SETTEXT or the buffer set by EM_SETHANDLE. 


This message undoes the last edit to the edit control. When 
the user modifies the edit control, the last change is stored 
in an undo buffer, which grows dynamically as required. If 
insufficient space is available for the buffer, the undo 
attempt fails and the edit control is unchanged. 


wParam and lParam are not used. 


Return Value The message returns nonzero if the undo operation is suc- 


cessful. It returns zero if it fails. 


Notes Implemented only for multiline edit controls. 

EM_CANUNDO 

Purpose This message determines whether an edit control can 
respond correctly to an EM_ UNDO message. 

Parameters  wParamand [Param are not used. 
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Return Value The return value is nonzero if the edit control can handle 


the EM_ UNDO message correctly. Otherwise, the return 
value Is zero. 


Notes Implemented only for multiline edit controls. 

EM_FMTLINES 

Purpose This message directs the edit control to add or remove the 
end-of-line character from word-wrapped text lines. 

Parameters _If wParam is nonzero, the characters CR CR LF (OD 0D 0A 


Return Value 


Notes 


WM_ CUT 


Purpose 


Parameters 


Return Value 


WM_ COPY 


Purpose 


Parameters 
Return Value 
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hexadecimal) are placed at the end of word-wrapped lines. If 
wParam is zero, the end-of-line marks are removed from the 
text. 


lParam is not used. 


EM_FMTLINES returns nonzero if any formatting was 
done, zero otherwise. 


Lines that end with a “hard” return (that is, a carriage 
return typed by the user), contain just the characters CR LF 
at the end of the line. These lines are not affected by the 
EM_FMTLINES message. 


Notice that the size of the text changes when this message is 
processed. 


This message sends the current selection to the clipboard in 
CF_ TEXT format, then deletes the selection from the con- 
trol window. 


wParam and [Param are not used. 


None. 


This message sends the current selection to the clipboard in 


CF_ TEXT format. 
wParam and lParam are not used. 


None. 
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WM_ PASTE 


Purpose This message inserts the data from the clipboard into the 
control window at the current cursor position. Data is 
inserted only if the clipboard contains data in CF_ TEXT 
format. 


Parameters wParam and lParam are not used. 


Return Value None. 


WM_ CLEAR 
Purpose This message deletes the current selection. 
Parameters wParam and [Param are not used. 


Return Value None. 


8.8.3 List Box Messages 


LB_ADDSTRING 


Purpose This message adds a string to the list box. If the list box is 
not sorted, the string is appended to the end of the list. 
Otherwise, it is inserted into the list after sorting. 


Parameters wParam is not used. 


[Param is a long pointer to the null-terminated string to be 
added. 


Return Value The list box returns the index to the string in the list box. 
LB_ ERR is returned if an error occurs; LB_-ERRSPACE is 
returned if insufficient space is available to store the new 


string. 

LB_INSERTSTRING 

Purpose This message inserts a string into the list box. No sorting is 
performed. 


Parameters wParamis an index to the position to receive the string. If 
wParam is —1, the string is appended to the end of the list. 
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The /Param parameter is a long pointer to the string. 


Return Value The return value is the index of the position where the string 
was inserted. LB_ ERR is returned if an error occurs; 
LB_ ERRSPACE is returned if insufficient space is available 
to store the new string. 

LB_ DELETESTRING 

Purpose This message deletes a string from the list box. 

Parameters wParamis an index to the string to be deleted. 


[Param is not used. 


Return Value The return value is a count of the strings remaining in the 
list. LB_ERR is returned if an error occurs. 


LB_SETSEL 
Purpose This message sets the selection state of a string. 


Parameters wParamis a Boolean value specifying how to set the selec- 
tion. If wParam is nonzero, the string is highlighted; if zero, 
any highlight is removed. 


The low-order word of [Param is an index that specifies 
which string to set. If /Param is —1, all the strings in the list 
are selected. 


Return Value LB_ERR is returned if an error occurs. 

Notes This message should be used only with multiple selection 
type list. boxes. 

LB_SETCURSEL 


Purpose This message selects a string and scrolls it into view, if 
necessary. When the new string is selected, the list box 
removes the highlight from the previously selected string. 


Parameters wParamis the index of the string to select: 
If [Param is —1, the list box is set to have no selection. 
Return Value LB_ERR is returned if an error occurs. 


Notes This message should only be used with single selection type 
list boxes. 
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LB_ GETSEL 


Purpose 


Parameters 


This message returns the selection state of an item. 
wParam is an index to the item. 


lParam is not used. 


Return Value LB_GETSEL returns a positive number if the items is 


selected, zero if not. LB_ ERR is returned if an error occurs. 


LB_ GETCURSEL 


Purpose 


Parameters 


This message returns the index of the currently selected 
item, if any. 


wParam and [Param are not used. 


Return Value LB-GETCURSEL returns the index of the currently selected 


item. It returns LB_ ERR if no item is selected or the list 
box has multiple selection type. 


LB_ GETTEXT 


Purpose 


Parameters 


This message copies a string from the list into a buffer. 
wParam is the index of the string to be copied. 


‘Param is a long pointer to the buffer to receive the string. 
The buffer must have sufficient space for the string and a 
terminating null character. 


Return Value The return value is the length of the string in bytes, exclud- 


ing the null character. It is LB_ERR if wParam is not a 
valid index. 


LB_ GETTEXTLEN 


Purpose 


Parameters 


This message returns the length of a string in the list box. 
wParam is an index to the string. 


lParam is not used. 


Return Value The return value is the length of the string in bytes, not 


including the terminating null character. LB_ERR is 
returned if an error occurs. 
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LB_ GETCOUNT 


Purpose 


Parameters 
Return Value 


This message returns a count of the number of items in the 
list box. 


wParam and [Param are not used. 


The return value is a count of the number of items in the list 
box. LB_ ERR is returned if an error occurs. 


LB_SELECTSTRING 


Purpose 


Parameters 


Return Value 


Notes 


LB_ DIR 


Purpose 


Parameters 


Return Value 
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This message changes the current selection to the first string 
having the specified prefix. 


wParam is the index of the starting point for the search. 
The starting point is not included in the search, so the value 
returned by LB_-GETCURSEL can be used as the starting 
point. If wParam is —1, the string is searched from the 
beginning. 


‘Param is a long pointer to the prefix string. The string 
must be null-terminated. 


The return value is the index of the selected item. LB_ ERR 
is returned if an error occurs. 


This message must not be used with list boxes having multi- 
ple selection type. 


A string is selected only if its initial characters (from the 
starting point) match the characters in the prefix string. 


This message adds a list of the files from the current direc- 
tory to the list box. Only files with the attributes specified 
by the wParam parameter and matching the file 
specification given by the /Param parameter are added. 


wParam parameter is an MS-DOS attribute value (see 
DlgDirList for a list of the attributes). 


The lParam parameter is a long pointer to a file specification 
string. The string can contain wildcard characters (e.g., *.*). 


The return value is a count of items displayed. LB_ ERR is 
returned if an error occurs; LB_- ERRSPACE is returned if 
insufficient space is available to store the new strings. 


Window Messages 


8.9 Notification Messages 


Button and edit controls use the WM_ COMMAND message to notify the 
parent window of actions that occur within the control. Unless an exception 
is noted, the wParam parameter of the WM_COMMAND message contains 
the control ID, the low-order word of [Param contains the edit control win- 
dow handle, and the high-order word of [Param contains a control 
notification code. 


The following sections describe the button, edit control, and list box 
notification codes. 


8.9.1 Button Notification Codes 


The following button notification codes apply to buttons with 
BS_ USERBUTTON style only. 


Code Meaning 

BN_ CLICKED The button has been clicked. 

BN_ PAINT Request to repaint the button. 

BN_ HILITE Request to highlight the button. 

BN_ UNHILITE Request to remove the highlight. 

BN_ DISABLE Request to draw a disabled button. 

Note In each case, the high-order word of the /Param 


parameter contains a window handle for the button. 


8.9.2 Edit Control Notification Codes 
Code Meaning 


EN_ SETFOCUS The edit control has obtained the input focus. 
EN_ KILLFOCUS The edit control has lost the input focus. 


EN CHANGE ‘The user has taken some action that may have 
changed the content of the text. 


EN_ ERRSPACE The edit control is out of space. 
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EN- HSCROLL The user has clicked the mouse on the edit control’s 
horizontal scroll bar. The parent window is notified 
before the screen is updated. 


EN_ VSCROLL The user has clicked the mouse on the edit control’s 
vertical scroll bar. The parent window is notified 
before the screen is updated. 


8.9.3 List Box Notification Codes 


The following notification codes apply only to list box controls that have 


the LBS_ NOTIFY style. 


Code Meaning 

LBN_ SELCHANGE The selection has been changed. 

LBN_- DBLCLK The user double clicked the mouse button over a 
string. 

LBN_ ERRSPACE Out of memory. 


8.10 Scroll Bar Messages 


Scroll bar controls send WM_ VSCROLL or WM_HSCROLL messages to 
their parents whenever the user clicks the mouse in the control. The 
wParam parameter contains the same values as defined for the scrolling 
messages for a standard window. The high-order word of [Param contains 
the window handle of the scroll bar control. 


8.11 Non-Client Area Messages 


This section describes messages that Windows sends to create and maintain 
the non-client area of a window. The non-client area is any portion of the 
window that is outside the client area, such as the caption bar and window 
frame. 


Normally, applications do not process these messages, but send them on to 
DefWindowProc for processing. 
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WM_NCCREATE 
Purpose This message is sent before the WM_ CREATE message 


when a window is first created. 
Parameters  wParamis a handle to the window being created. 


lParam is a long pointer to the CREATESTRUCT data 


structure for the window. 


Default Action Scroll bars are initialized (the scroll bar data structure is 
allocated, and the scroll bar position and range are set) and 
the window text is set. Memory used internally to create 
and maintain the window is allocated. 


Return Value WM_—NCCREATE returns a nonzero value if the non-client 
area is created. If an error occurs, the return value is zero; 
the Create Window call will return NULL in this case. 

WM_NCDESTROY 


Purpose This message is sent after the WM_ DESTROY message. It 
is used to destroy the allocated memory block associated 
with the window. 


Parameters wParam and lParam are not used. 


Default Actton Memory associated with the window is freed. 


WM_ NCCALCSIZE 


Purpose This message is sent when the size of a window’s client area 
needs to be calculated. 


Parameters wParam is not used. 


[Param is a long pointer to a RECT data structure contain- 
ing the screen coordinates of the window rectangle (includ- 
ing client area, borders, caption, scroll bars, etc.) 


Default Actton DefWindowProc calculates the size of the client area, 
based on the window characteristics (presence of scroll bars, 
menu, etc.) and places the result in the RECT data struc- 
ture. 
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WM_NCHITTEST 


Purpose Every time the mouse is moved, this message is sent to the 
window containing the mouse cursor (unless a window has 
captured the mouse). 


Parameters wParam is not used. 


lParam contains the x and y coordinates of the mouse cur- 
sor. The x coordinate is in the low-order word; the y- 
coordinate is in the high-order word. These coordinates are 
always relative to the top left corner of the window. 


Default Actton The return value of DefWindowProc is one of the follow- 
ing values indicating the position of the mouse cursor: 


Value Position 

HTNOWHERE On the screen background or on a 
dividing line between windows. 

HTERROR Same as HTNOWHERE except 


that DefWindowProc produces a 
system beep to indicate an error. 


HTTRANSPARENT In a window currently covered by 


another window. 


HTCLIENT Client area. 
HTCAPTION Caption area. 
HTSYSMENU System menu box (close box in 
child windows). 
HTGROWBOX Size box. 
HTMENU Menu area. 
HTHSCROLL Horizontal scroll bar. 
HTVSCROLL Vertical scroll bar. 
Notes The MAKEPOINT macro can be used to convert the [Param 


parameter to a POINT. 
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WM_NCPAINT 
Purpose This message is sent to a window when its frame needs 
painting. 


Parameters wParam and lParam are not used. 
Default Actton DefWindowProc paints the window frame. 


Notes An application can intercept this message and paint its own 
custom window frame. However, remember that the clip- 
ping region for a window is always rectangular, even if the 
shape of the frame is altered. 


WM_NCACTIVATE 

Purpose This message is sent to a window when its caption bar or 
icon needs to be changed to indicate an active or inactive 
state. 


Parameters wParam is nonzero if an “active” caption or icon is to be 
drawn. It is zero for an inactive caption or icon. 


Default Action DefWindowProc draws a gray caption bar for an inactive 
window, a black caption bar for an active window. An 
active window that is iconic is framed in white. 


WM_NCMOUSEMOVE 


Purpose This message is sent to a window whenever the mouse is 
moved in a non-client area of the window. 


Parameters wParam contains the code returned by the 


WM_ NCHITTEST message (see WM_ NCHITTEST). 


[Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 


Default Action If appropriate, WM_SYSCOMMAND messages are sent. 
WM_NCLBUTTONDOWN 


Purpose This message is sent to a window whenever the left mouse 
button is pressed while the mouse is in a non-client area of 
the window. 
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Parameters 


wParam contains the code returned by the 


WM_ NCHITTEST message (see WM_ NCHITTEST). 


[Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 


Default Action If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCLBUTTONUP 


Purpose 


Parameters 


This message is sent to a window whenever the left mouse 
button is released in a non-client area of the window. 


wParam contains the code returned by the 


WM_ NCHITTEST message (see WM_ NCHITTEST). 


[Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 


Default Action If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCLBUTTONDBLCLK 


Purpose 


Parameters 


This message is sent to a window whenever the left mouse 
button is double clicked in a non-client area of the window. 


wParam contains the code returned by the 


WM_ NCHITTEST message (see WM_ NCHITTEST). 


[Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 


Default Actton If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCRBUTTONDOWN 


Purpose 


This message is sent to a window whenever the right mouse 
button is pressed while the mouse is in a non-client area of 
the window. 


Parameters wParam contains the code returned by the 
WM_ NCHITTEST message (see WM_ NCHITTEST). 
(Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 

Default Action None. 
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WM_NCRBUTTONUP 


Purpose 


This message is sent to a window whenever the right mouse 
button is released in a non-client area of the window. 


Parameters wParamcontains the code returned by the 
WM_ NCHITTEST message (see WM_ NCHITTEST). 
[Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 

Default Action None. 


WM_NCRBUTTONDBLCLK 


Purpose This message is sent to a window whenever the right mouse 
button is double clicked in a non-client area of the window. 

Parameters wParam contains the code returned by the 
WM_ NCHITTEST message (see WM_ NCHITTEST). 
[Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 

Default Action None. 

WM_NCMBUTTONDOWN 

Purpose This message is sent to a window whenever the middle 
mouse button is pressed while the mouse is in a non-client 
area of the window. 

Parameters wParam contains the code returned by the 
WM_ NCHITTEST message (see WM. NCHITTEST). 
(Param is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 

Default Action None. 

WM_NCMBUTTONUP 

Purpose This message is sent to a window whenever the left mouse 
button is released in a non-client area of the window. 

Parameters wParamcontains the code returned by the 


WM_ NCHITTEST message (see WM_ NCHITTEST). 
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lParam is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 


Default Action None. 
WM_ NCMBUTTONDBLCLK 


Purpose This message is sent to a window whenever the middle 
mouse button is double clicked in a non-client area of the 
window. 


Parameters wParamcontains the code returned by the 


WM_ NCHITTEST message (see WM_ NCHITTEST). 


lParam is a POINT data structure containing the x and y 
screen coordinates of the mouse position. 


Default Actton None. 
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Raster Operation Codes And Definitions 


A.1 Introduction 


This appendix lists the raster operation codes used by the PatBlt, BitBlt, 
and StretchBlt functions. The raster operation codes define how GDI 
combines the bits in a source bitmap with the bits in the destination bit- 
map. 


Each raster operation code represents a Boolean operation in which the 
source, the currently selected brush, and the destination are combined. 
The operands used in the operations are: 


S Source bitmap 
P Currently selected brush (also called pattern) 
D Destination bitmap 


The Boolean operators used in these operations are: 


Bitwise Or 

Bitwise Exclusive Or 
Bitwise And 

Bitwise Not (inverse) 


—~ © KO 


All Boolean operations are presented in reverse Polish notation. For exam- 
ple, the operation 


PSo 


replaces the destination with a combination of the source and brush. The 
operation 


DPSoo 

combines the source and brush with the destination. Note that there are 
alternate spellings of the same function so although a particular spelling 
may not be in the list, an equivalent form will be. 

Each raster operation code is a 32-bit integer value whose high-order word 


is a Boolean operation index and low-order word is the operation code. The 
16-bit operation index is a zero-extended 8-bit value which represents the 
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result of the Boolean operation on predefined brush, source, and destination 
values. For example, the operation indexes for the PSo and DPSoo opera- 
tions are: 


P S D | PSo DPSoo 
ee | sacar pecs 
| 

oc € | O O 

Oo Oo | | O 1 

Go 1 €¢ 7 1 1 

i a 1 iL 

1 OF ODO ff 1 1 

1 QO 1 | id. 1 
iil © | 1 - 

i ee er) 1 HR 
Operation index: OOEC OOFE 


In this case, PSo has the operation index OOFC (read from bottom up); 
DPSoo has the index OOFE. These values define the location of the 
corresponding raster operation code in the following table. The PSo opera- 
tion is in line 252 (FC hex) of the table; DPSoo in line 254 (hex FE). 


The most commonly used raster operations have been given special names 
in the Windows include file. Programmers should use these names when- 
ever possible in their applications. 


A.2 Operation Codes 


This section lists the raster operation codes. 


Boolean Boolean 
Function HEX Function Common 
In HEX Rop In R Polish Name , 
OO O0000042 O BLACKNESS 
O1 00010289 DPSoon 2. 
O2 O00 20C89 DPSona = 
O3 OOO 300AA PSon = 
04 O00040C88 SDPona sa 
O5 OOO500A9 DPon = 
O06 O0060865 PDSxnon : 
O'7 000702C5 PDSaon 7 


412 


OOO80F 08 
00090245 
OQ0A0N 329 
OOOBOB2A 
000C0324 
OOODOB25 
OOOEO8AS 
OOOFOOO01 
00100C85 
001100A6 
00120868 
001 302C8 
00140869 
001502C9 
OO165CCA 
00171D54 
O0180D59 
00191CC8 
OO1LAOQ6CS 
001B0768 
O0O1CO6CA 
001D0766 
OO1LEO1AS 
OO1LFO385 
OO200F 09 
00210248 
00220326 
00230B24 
O0O0240D55 
00251CC5 
002606C8 
00271868 
00280369 
OO2Z2916CA 
OO2ZA0CCYI 
OO2B1D58 
002C0784 
OO2ZDO60A 
OO2Z2E064A 
OO2ZFOE2A 
0030032A 
00310B28 
00320688 
00330008 
003406C4 
00351864 
OO03601A8 
00370388 
0038078A 
00390604 
003A0644 
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DPSaon 
PSDPSanaxx 
oSPxDSxaxn 
SPxPDxa 
SDPSanaxn 
PDSPaox 
SDPSxaxn 
PSDPaox 
DSPDxaxn 
PDSox 
PDSoan 
DPSnaa 

SDP xon 
DSna 
SPDnaon 
SPxDSxa 
PDSPanaxn 
SDPSaox 
SDPSxnox 
DPSxa 
PSDPSaoxxn 
DPSana 
SsoPxPDxaxn 
SPDSoax 
PSDnox 
PSDPxox 
PSDnoan 
PSna 
SDPnaon 
SDPSoox 

on 

SPDSaox 
SPDSxnox 
SDPox 
SDPoan 
PSDPoax 
SPDnox 
SPDSxox 
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414 


OO 3BOE 24 
00 3CO04A 
003D18A4 
OO3E1B24 
OO3FOOEA 
OO400F OA 
00410249 
00420D5D 
00431CC4 
00440328 
00450B29 
004606C6 
0047076A 
00480368 
004916C5 
004A0789 
OO4B0605 
O004COCC8 
O004D1954 
OO4E0645 
OO4FOE 25 
00500325 
00510B26 
005206C9 
00530764 
005408A9 
00550009 
OO5601A9 
00570389 
00580785 
00590609 
OOSAO0049 
OOSB18A9 
005C0649 
OOSDOE 29 
OOSE1B29 
OOSFOOE9 
00600365 
006116C6 
00620786 
006 30608 
00640788 
00650606 
00660046 
006718A8 
O06858A6 
00690145 
OO6AO0O1LEY 
OO6B178A 
OO6CO1E8 
006D1785 


SPDnoan 
PSx 
SPDSonox 
SPDSnaox 
PSan 
PSDnaa 
DPSxon 
SDxPDxa 
SPDSanaxn 
sDna 
DPSnaon 
DSPDaox 
PSDPxaxn 
SDPxa 
PDSPDaoxxn 
DPSDoax 
PDSnox 
SDPana 
SSPxDSxoxn 
PDSPxox 
PDSnoan 
PDna 
DSPnaon 
DPSDaox 
SPDSxaxn 
DPSonon 
Dn 

DPSox 
DPSoan 
PDSPoax 
DPSnox 
DPx 
DPSDonox 
DPSDxox 
DPSnoan 
DPSDnaox 
DPan 
PDSxa 
DSPDSaoxxn 
DSPDoax 
SDPnox 
SDPSoax 
DSPnox 
DSx 
SDPSonox 


DSPDSonoxxn 


PDSxxn 
DPSax 
PSDPSoaxxn 
SDPax 
PDSPDoaxxn 


SRCINVERT 


OO6E1E28 
OO6FOCES 
007 00CCS 
00711D5C 
007 20648 
007 30E 28 
00740646 
00'750E 26 
00761B28 
0077'/00E6 
O0O7801E5 
00791786 
OO7ALE29 
007 BOC68 
OO7C1E24 
00'7DOC69 
OO7EO9S5 
OO7FO3C9 
O08003E9 
00810975 
008 20C49 
008 31E04 
00840C48 
OO851E05 
008617A6 
008701C5 
OO8800CE6 
00891B08 
OO8AOEO06 
OO8BO666 
OO8COEO08 
OO08D0668 
OO8BE1D7C 
OO8FOCE5 
00900C45 
00911E08 
00921'77A9 
009301C4 
0094177AA 
O009501C9 
00960169 
0097588A 
00981888 
00990066 
O09A0709 
OO9B07A8 
009C0704 
OO9D07A6 
OOJE16E6 
OO9FO345 
OOAOQO0C9 
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SDPSnoax 
PDSxnan 
PDSana 
SSDxPDxaxn 
SDPSxox 
SDPnoan 
DSPDxox 
DSPnoan 
SDPSnaox 
DSan 
PDSax 
DSPDSoaxxn 
DPSDnoax 
SDPxnan 
SPDSnoax 
DPSxnan 
SPxDSxo 
DPSaan 
DPSaa 
SPxDSxon 
DPSxna 
SPDSnoaxn 
SDPxna 
PDSPnoaxn 
DSPDSoaxx 
PDSaxn 
DSa 
SDPSnaoxn 
DSPnoa 
DSPDxoxn 
SDPnoa 
SDPSxoxn 
SSDxPDxax 
PDSanan 
PDSxna 
SDPSnoaxn 
DPSDPoax~x 
SPDaxn 
PSDPSoaxx 
DPSaxn 
DPSxx 
PSDPSonoxx 
SDPSonoxn 
DSxn 
DPSnax 
SDPSoaxn 
SPDnax 
DSPDoaxn 
DSPDSaoxx 
PDSxan 
DPa 
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416 


OOA11BO5 
OOA2Z0EO9 
OOA30669 
O0OA41885 
OOASO065 
OOA60706 
OOA707A5S 
OOA80 3A9 
OOAI0189 
OOAAO00 29 
OOABO889 
OOACO744 
OOADO6EY 
OOAEOBO6 
OOAFO229 
OOBOOEOS 
OOB10665 
00B21974 
OOB30CE8 
OOB4070A 
OOB507A9 
OOB616E9 
00B70348 
OOB8074A 
OOBYO06E6 
OOBAOBO9 
OOBBO2 26 
OOBCI1CE4 
OOBDOD7D 
OOBEO 269 
OOBF O8C9 
OOCOOO0CA 
O0C11B04 
00C21884 
OOC3006A 
OOC40E04 
O0C50664 
00C60708 
O0C7O7AA 
O0C803A8 
O00C90184 
OOCAO749 
OOCBO6E4 
OOCCO00 20 
OOCDO0888 
OOCEOBO8 
OOCFO224 
OODOOEOA 
OOD1O66A 
O00D20705 
OOD307A4 


PDSPnaoxn 
DPSnoa 
DPSDxoxn 
PDSPonoxn 
PDxn 
DSPnax 
PDSPoaxn 
DPSoa 
DPSoxn 

D 

DPSono 
SPDSxax 
DPSDaoxn 
DSPnao 
DPno 
PDSnoa 
PDSPxoxn 
SSPxDSxox 
sDPanan 
PSDnax 
DPSDoaxn 
DPSDPaoxx 
SDPxan 
PSDPxax 
DSPDaoxn 
DPSnao 
DSno 
SPDSanax 
SDxPDxan 
DPSxo 
DPSano 
PSa 
SPDSnaoxn 
SPDSonoxn 
PSxn 
SPDnoa 
SPDSxoxn 
sSDPnax 
PSDPoaxn 
SDPoa 
SPDoxn 
DPSDxax 
oPDSaoxn 
S 

SDPono 
SDPnao 
SPno 
PSDnoa 
PSDPxoxn 
PDSnax 
SPDSoaxn 


MERGEPAINT 


MERGECOPY 


OOD41D78 
OODSOCE9 
OOD616EA 
O00D70349 
00D80745 
OOD9Y06E8 
OODA1CE9 
OODBOD75 
OODCOBO4 
OODDO2 28 
OODEO268 
OODF O08C8 
OOQEOO3A5 
OOE10185 
OOE 20746 
OOE 306EA 
OOE40748 
OOESO6E5 
OOE61CE8 
OOE'70D79 
OOE81D74 
OOE9YSCE6 
OOEAO2E9 
OOEBO849 
OOECO2E8 
OOEDO848 
OOEEOO86 
OOEF OAO08 
OOFOOO021 
OOF 10885 
OOF 20B05 
OOF 3022A 
OOF 40BOA 
OOF 50225 
OOF 60265 
OOF’708C5 
OOF 802E5 
OOF 90845 
OOF A0089 
OOF BOAOY 
OOF COO8A 
OOF DOAOA 
OOFEO2A9 
OOFFOO062 
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SSPxPDxax 
DPSanan 
PSDPSaoxx 
DPSxan 
PDSPxax 
SDPSaoxn 
DPSDanax 
SPxDSxan 
SPDnao 
SDno 
SDPxo 
SDPano 
PDSoa 
PDSoxn 
DSPDxax 
PSDPaoxn 
SDPSxax 
PDSPaoxn 
SDPSanax 
SPxPDxan 
SSPxDSxax 


DSPDSanaxxn 


DPSao 
DPSxno 
SDPao 
SDPxno 
DSo 
SDPnoo 
Pp 
PDSono 
PDSnao 
PSno 
PSDnao 
PDno 
PDSxo 
PDSano 
PDSao 
PDSxno 
DPo 
DPSnoo 
PSo 
PSDnoo 
DPSoo 
1 


SRCPAINT 


PATCOPY 


PATPAINT 


WHITENESS 
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Appendix B 
Virtual Key Code Summary 


This appendix describes the Windows virtual key set. The virtual key set 
consists of 256 virtual keys, numbered from 0 to 255. The keys from 0 to 
127 are called the Windows-defined virtual keys. The keys from 128 to 255 
are called OKM-defined virtual keys. The Windows-defined virtual keys are 
divided into three groups: standard, extended, and reserved. 


Every OEM adaptation of Windows must be capable of generating: 


Keys Definition 

Standard Keys The Windows-defined standard virtual 
keys. 

Letter Combination Keys Key combinations consisting of a SHIFT, 


CONTROL, or CONTROL-SHIFT and a letter 
key (65 through 90). 


Cursor Combination Keys Key combinations consisting of a SHIFT, 
CONTROL, or CONTROL-SHIFT and a cursor 
key (left, right, up, and down). 


Function Keys A minimum of 10 function keys, f1 
through f10. It is possible to query the 
OEM layer to determine the actual 
number of supported function keys. 


Function Combination Keys Key combinations consisting of a SHIFT, 
CONTROL, or CONTROL-SHIFT and a func- 
tion key. 


Implementation of all other keys is entirely OEM dependent: 


In the listing below, the unused entries are empty, the extended keys are 
marked with an asterisk (*), and all others are standard. The extended 
keys 96 through 111 are numeric key pad digits and operators found on a 
keypad. 
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O 1 2 a 4 5 6 7 

O shift space O P *numpadO fl 

1 *lbutn control prior ‘i A Q *numpadl f2 

2 *rbutn menu next 2 B R *numpad2 f3 

3 cancel * pause *end 3 cy 5 *numpad3 f4 

4 *mbutn capital home 4 D T *numpad4 f5 

5 left 5 E U *numpadsS f6 

6 up 6 E V *numpad6 f7 

7 right 7 G W *numpad7 £8 

8 backsp down 8 H X *numpadsg f9 

9 tab *select 9 I ¥ *numpad9 £10 
a Forint J fg * 50 3 
b escape *execute K - we) NY 
c *clear L * Sfi3 
d return ins M iain a te: 
e del N * "ELS 
f *help O By * £16 


If an OEM has a keyboard that has the following symbols on a single key- 
cap, then the following are suggested as part of the country-specific OEM- 
defined virtual key set. 


YS: Japan France Germany Spain Italy Sweden 
BA , 3 s # a 8 < 12 ; 3 < > " # 
BB =. af 2 + =: + + * = + + * + # 
BC < < ? x 7 ? , | 
BD 2 - = re Mt me rt me 
BE x 2 . = ; ! 
BE J? Fe ss ? > ae < > 
CO bq ~ ‘-@ bq bq lb ac gr or cr ugr sec ac gr 
DB [ { ( { ) deg Aum ac um agr # Aum 
DC % | yn | ugr % Oum Ntl ogr @ Oum 
DD ] ] } = > Uum Ccd egr eac Arn 
DE = _— cr um $+ . igr ™ um cr 
DF ase 


ss-German sharp s 
bq-back quote 
lb-British Pound 
yn-Japanese Yen 
sec-section symbol 
deg-degree symbol 
ac-acute accent 
gr-grave accent 
cr-circumflex 
cd-cedilla 
um-umlaut 

rn-ring 

tl-tilde 
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Notes 


Windows uses the OEM-supplied ToAscii function to convert virtual 
key codes into the corresponding ASCII value. To make this conversion 
simple, some virtual keys have the same value as the corresponding 
ASCII character. For example, the virtual key code for VK_A is equal 
to 65, the ASCII value of the capital letter “A.” 


Since Windows can be run using the keyboard interface only, the mouse 
keys (1, 2, and 4) are not part of the standard set. 
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Font Files 


C.1 
C.2 
C.2.1 
O.2.2 


Introduction 425 

Font File Formats 4295 
Raster Font File Format 
Vector Font File Format 


C.3 ANSI Character Set 432 


430 
431 
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Font Files 


C.1 Introduction 


The standard FONTS.FON file provided with Windows includes fonts for 
both 2:1 and 1:1 aspect ratio displays and only the fonts whose aspect ratio 
matches the display are actually used. There are three sizes of fonts pro- 
vided in the ANSI character set: 6, 8, and 11 pixels high for 2:1 displays 
and 12, 16, and 22 pixels high for 1:1 displays. There is only one 1:1 and 
one 2:1 OEM-dependent font. There are both Terminal and Document 
faces in each size. 


Windows is capable of synthesizing attributes, such as bold, italic, and 
underlined, so such fonts are not in FONTS.FON. The fonts that do not 
correspond to the user’s display aspect ratio are nevertheless generic raster 
fonts that can be used for output devices such as bitmap printers. 


C.2 Font File Formats 


Formats for font files are defined for both raster and vector fonts. These 
formats may be used by smart text generators in some GDI support 
modules. The vector formats, in particular, are more frequently used by 
GDI itself than by support modules. 


Both types of files begin with information which is common to both, and 
then continue with information which differs for each type of file. Font files 
are stored with a .fnt extension of the form name.fnt. The information at 
the beginning of both types of files is as follows: 


Field Definition 

dfVersion Two bytes specifying the version of the file 
(currently 256). 

dfSize Four bytes specifying the total file size in bytes. 

dfCopyright Sixty (60) bytes specifying copyright informa- 
tion. 

dfType Two bytes specifying the type of font file. The 


low-order byte is for exclusive GDI use. If the 
low-order bit of the word is 0, it is a bitmap (ras- 
tor) font file. If the low-order bit is 1, it is a vec- 
tor font file. The second bit is reserved and must 
be zero. If no bits follow in the file and the bits 
are located in memory at a fixed address 
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dfPoints 


dfVertRes 


dfHorizRes 


dfAscent 


dfInternalLeading 


dfExternalLeading 


dfItalic 


426 


specified in dfBitsOffset, the third bit is set to 1; 

otherwise, the bit is set to 0. The high bit of the 
low-order byte is set if the font was realized by a 
device. The remaining bits in the low-order byte 
are reserved and set to zero. 


The high-order byte is reserved for device use 
and will always be set to zero for GDI realized 
standard fonts. Physical fonts with the high bit 
of the low-order byte set may use this byte to 
describe themselves. GDI will never inspect the 
high-order byte. 


Two bytes specifying the nominal point size at 
which this character set looks best. 


Two bytes specifying the nominal vertical resolu- 
tion oe per inch) at which this character set 
was digitized. 


Two bytes specifying the nominal horizontal 
resolution (dots per inch) at which this character 
set was digitized. 


Two bytes specifying the distance from the top 
of a character definition cell to the baseline of 
the typographical font. It is useful for aligning 
the baseline of fonts of different heights. 


Two bytes specifying the amount of leading 
inside the bounds set by dfPizHeight. Accent 
marks may occur in this area. This may be zero 
at the designer’s option. 


Two bytes specifying the amount of extra lead- 
ing that the designer requests the application 
add between rows. Since this area is outside of 
the font proper, it contains no marks, and will 
not be altered by text output calls in either 


OPAQUE or TRANSPARENT mode. This may 


be zero at the designer’s option. 


One byte specifying whether the character 
definition data represent an italic font. The 
low-order bit is one if the flag is set. All other 
bits are zero. 


dfUnderline 


dfStrikeOut 


dfWeight 


dfCharSet 


dfPix Width 


dfPixHeight 


dfPitchAndF amily 


Font Files 


One byte specifying whether the character 
definition data represent an underlined font. 
The low-order bit is one if the flag is set. All 
other bits are zero. 


One byte specifying whether the character 
definition data represent a strikeout font. The 
low-order bit is one if the flag is set. All other 
bits are zero. 


Two bytes specifying the weight of the charac- 
ters in the character definition data, on a scale 
from 1-1000. A weight of 100 is the usual for 
light type, 200 specifies regular, 300 semibold, 
and so forth. 


One byte specifying the character set defined by 
this font. The IBM“ PC hardware font has been 
assigned the designation 377 octal (FF hexadeci- 
mal or 255 decimal). 


Two bytes. For vector fonts, specifies the width 
of the grid on which the font was digitized. For 
raster fonts, if dfPtxWtdth is nonzero, it 
represents the width for all characters in the bit- 
map; if it is zero, the font has variable width 
characters whose widths are specified in the 


dfCharOffset array. 


Two bytes specifying the height of the character 
bitmap (raster fonts}, or the height of the grid 
on which a vector font was digitized. 


Specifies the pitch and font family. The low bit 
is set if the font is variable-pitch. The four 
high-order bits give the family name of the font. 
The values are: 


FF_DONTCARE (0<<4) 
FF_ROMAN = (1<<4) 
FF_SWISS = (2<<4) 
FF_MODERN —_ (3< <4) 
FF_SCRIPT  (4<<4) 
FF_DECORATIVE (5<<4) 


Font families describe in a general way the look 
of a font. They are intended for specifying fonts 
when the exact facename desired is not available. 
The families are: 
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dfAvg Width 


dfMax Width 


dfFirstChar 


dfLastChar 


dfDefaultChar 
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FF_ DONTCARE 


Don’t care or don’t know. 


FF_ ROMAN 
Fonts with variable stroke width, ser- 
ifed. Times Roman, Century School- 
book, etc. 


FF_ SWISS 
Fonts with variable stroke width, 
sans-serifed. Helvetica, Swiss, etc. 


FF_ MODERN 
Fonts with constant stroke width, ser- 
ifed or sans-serifed. Fixed-pitch fonts 
are usually modern. Pica, Elite, 
Courier, etc. 


FF_ SCRIPT 


Cursive, etc. 


FF_ DECORATIVE 
Old English, ete. 


Two bytes specifying the width of characters in 
the font. For fixed-pitch fonts this is the same as 
dfPizWidth. For variable-pitch fonts this is the 
width of the character ‘X’. 


Two bytes specifying the maximum pixel width 
of any character in the font. For fixed-pitch 
fonts, this is simply dfPex Width. 


One byte specifying the first character code 
defined by this font. Character definitions are 
stored only for the characters actually present in 
a font, so use this field when calculating indexes 


into either dfBits or dfCharOffset. 


One byte specifying the last character code 
defined by this font. Note that all characters 
with codes between dfFirstChar and dfLastChar 


must be present in the font character definitions. 


One byte specifying the character to substitute 
whenever a string contains a character out of the 
range dfFirstChar through dfLastChar. The 
character is given relative to dfFirstChar so that 
dfDefaultChar is the actual value of the character 
less dfFirstChar. dfDefaultChar should indicate a 
special character in the font which is not a space. 


dfBreakChar 


dfWidthBytes 


dfDevice 


dfFace 


dfBitsPointer 


dfBitsOffset 


dfCharOffset 


Font Files 


One byte specifying the character that will define 
word breaks. This character defines word breaks 
for word wrapping and word spacing 
justification. The character is given relative to 
dfFirstChar so that dfBreakChar is the actual 
value of the character less dfFirstChar. 
dfBreakChar is normally (32 - dfFirstChar), which 
is an ASCII space. 


Two bytes specifying the number of bytes in 
each row of the bitmap (raster fonts). No mean- 
ing for vector fonts. dfWidthBytes is always an 
even quantity so that rows of the bitmap start 
on word boundaries. 


Four bytes specifying the offset in the file to the 
string giving the device name. For a generic 
device, this value will be zero (0). 


Four bytes specifying the offset in the file to the 
null-terminated string that names the face. 


Four bytes specifying the absolute machine 
address of the bitmap. This is set by GDI at 
load time. dfBitsPointer is guaranteed to be 
even. 


Four bytes specifying the offset in the file to the 
beginning of the bitmap information. If the 04h 
bit in dfType is set, then dfBitsOffset is an abso- 
lute address of the bitmap. (Probably in ROM) 
For raster fonts, it points to a sequence of bytes 
that makes up the bitmap of the font, whose 
height is the height of the font, and whose width 
is the sum of the widths of the characters in the 
font rounded up to the next word boundary. For 
vector fonts, it points to a string of bytes or 
words (depending on the size of the grid on 
which the font was digitized) specifying the 
strokes for each character of the font. 
dfBitsOffset must be even. 


For proportionally spaced raster fonts, this field 
contains two bytes giving the offset from the 
start of each bitmap row for each character in 
the set. The number of characters present in the 
sel is calculated as 1 at ane an ple alrigg +1) 
and one spare, used for the senttnel offset. The 


total is therefore ((dfLastChar—dfFirst Char)+2) 
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entries, each of two bytes. For equal-width ras- 
ter fonts, this field collapses to zero size because 
all widths may be obtained by looking up the 
width in dfPixWidth. 


For fixed-pitch vector fonts, each two-byte entry 
in this array specifies the offset from the start of 
the bitmap to the beginning of the string of 
stroke-specification units for the character. The 
number of bytes or words to be used for a partic- 
ular character is calculated in the same fashion 
as the width of a raster character (i.e., subtract 
its entry from the next one), so that both types 
of font require a sentinel value at the end of the 
array of values. 


For proportionally spaced vector fonts, each 
four-byte entry is divided into two two-byte 
fields. The first field gives the starting offset from 
Lhe start of the bitmap of the character strokes 
as for fixed-pitch fonts. The second field gives 
the pixel width of the character. 


<facename > An ASCII character string specifying the name of 
the font face. The size of this field is the length 
of the string plus a null terminator. 


<devicename > An ASCII character string specifying the name of 
the device if this font file is for a specific device. 
The size of this field is the length of the string 
plus a null terminator. 


< bitmaps > This field contains the bitmap definitions. The 
size of this field depends on the length of the bit- 
map definitions. Each row of a raster bitmap 
must start on a word boundary. This implies 
that the end of each row must be padded to an 
even length. 


C.2.1 Raster Font File Format 


In addition to the information in the header to the file, a raster font file 
contains a string of bytes which is the actual bitmap, just as it will be 
loaded into contiguous memory. That string begins in the file at the offset 
specified in the fiBits field above. 
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C.2.2 Vector Font File Format 


The header information for a vector font file is as described in Section C.2, 
“Font File Formats.’’ This section describes some additional information 
for vector font files. 


The CharOffset field is used to specify the location and usage of the charac- 
ter strokes in the bitmap area. For fixed-pitch fonts, each two-byte entry is 
an offset from the start of the bitmap to the beginning of the strokes for 
the character. For variable-pitch fonts, each four-byte entry consists of 
two bytes giving the offset (as for fixed-pitch) and two bytes giving the 
width of the character. 


For both fixed- and variable- pitch fonts, the bitmap area is the same. 
Each character is composed of a series of vectors consisting of a pair of 
signed relative coordinate pairs starting from the character cell origin. 
Each pair may be preceded by a special value indicating that the next coor- 
dinate is to be a pen-up move. The special pen-up value depends on how 
the coordinates are stored. For one-byte quantities, it is -128 (O80H) and 
for two-byte quantities, it is -32768 (O8000H). 


The character cell origin must be at the upper left corner of the cell so that 
the character hangs down and to the right of where it is placed. 


The storage format for the coordinates depends on the size of the font. If 
either dfPixHeight or dfMaxWidth is greater than 128, the coordinates are 
stored as 2-byte quantities; otherwise, they are stored as 1-byte quantities. 
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C.3 ANSI Character Set 


Table C.1 


ANSI Character Set For Windows 


ca 
— Ue m Zo ¢ —— ee | eS ee de oO 
Q : 
—e ee eee | ee, es 
O 
ee | ee ee | 
jaa 
Oo mm + eo ee OS eS OF Wt Ide 
< 
CS meme ee OS ee re eH ee Oo) ol a ofa 
o> 
a ee i ee ee 
00 
CO mmm —=2 cS CO > oe 4a) a “eS 
t 
COC Mt mm- re esos a = ee _- 2 Ws, 
<<] 


> 
Cm mee ww SS wa DS ee oe OS oD i 
= 
ee ee ee | Co foo fo tS 


~* 
CO mm mm Str ots to WwW oe Oo ss os ae 
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ABORTDOC escape, 176 
ABSOLUTE mode, 142 
ACCELERATORS resource, 286 
Accelerators 

loading, 212 

resource, 286 

translating, 16 
AccessResource, 215 
Active window, 36 
AddAtom, 220 
AddFontResource, 207 
AllocResource, 214 
ALTERNATE mode, 147 
ANSI_ CHARSET, 263 
ANSI_ FIXED_ FONT object, 128 
AnsiLower, 218 
AnsiNext, 219 
AnsiPrev, 219 
AnsiToOem, 217 
AnsiUpper, 218 
ANSI VAR_ FONT object, 128 
AnyPopup, 37 
Arc, 114 
Area filled, 124 
Arg, 342 
Ascent, 268 
Aspect ratio, 269 
ASPECTX capability, 184 
ASPECTXY capability, 184 
ASPECTY capability, 184 
Assembly-language macros. See 

Cmacros 
assumes macro, 333 
Atoms, 219, 220, 221 
Attribute functions. See Windows, 
attribute functions 


Background 
brush, 256 
color 
default, 71 
retrieving, 143 
setting, 142 
erasing, 357 


Background (continued) 
mode 
default, 71 
retrieving, 144 
setting, 143 
Baud rate, 273 
BeginPaint, 73 
Binary raster operation, 145 
Bit level transfers 
copying, 116 
patterns, 115 
stretching, 117 
Bit patterns, drawing, 115 
BitBlt, 116 
BITMAP data structure, 265 
Bitmap format, 47, 49, 51. See also 
Display format 
BITMAP resource, 282 
Bitmaps 
bits per pixel, 265 
bits per raster line, 265 
color planes, 265 
compatible with a display, 132 
copying, 116, 117 
creating, 131, 132 
data structure, 265 
deleting, 138 
device-independent format, 209 
height, 265 
loading, 209 
moving, 116 
physical dimensions, 134 
retrieving, 140 
retrieving bits, 133 
selecting, 138 
setting bits, 133 
setting physical dimensions, 133 
stretching, 117 
type, 265 
width, 265 
BITSPLIXEL capability, 184 
BLACK_ BRUSH object, 127 
BLACKONWHITE mode, 146 
BLACK_ PEN object, 128 
Blink rate (cursor), 320 
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BM_ GETCHECK message, 388 
BM_ GETSTATE message, 389 
BM_ SETCHECK message, 389 
BM_SETSTATE message, 389 
BN_ CLICKED code, 401 
BN_ DISABLE code, 401 
BN_ HILITE code, 401 
BN_ PAINT code, 401 
BN_ UNHILITE code, 401 
BOOL type, 251 
Border, 28 
Break character, 165 
BringWindowToTop, 36 
Brushes 

color, 260 

creating, 129, 131 

default color, 71 

default origin, 158 

deleting, 138 

enumerating, 181 

hatch style, 261 

hatched, 130 

origin, 158 

patterned, 130 

retrieving, 140 

selecting, 138 

setting origin, 158 

solid, 129 

stock, 127 

style, 260 
BS_ 3STATE style, 302 
BS_ AUTO3STATE style, 302 
BS_ AUTOCHECKBOxX style, 302 
BS_ CHECKBOX style, 302 
BS_ DEFPUSHBUTTON style, 302 
BS_ GROUPBOX style, 302 
BS_ HATCHED brush, 260 
BS_ HOLLOW brush, 260 
BS_ PATTERN brush, 260 
BS_ PUSHBUTTON style, 302 
BS. RADIOBUTTON style, 302 
BS SOLID brush, 260 
BS_ USERBUTTON style, 302 
BuildCommDCB, 228 
BUTTON control class, 300 
Button control messages, 388 
BUTTON control styles, 302 
Button notification codes, 401 
BYTE type, 251 
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Call macros, 341 
Calling convention 

Cmacros, 329 

Pascal, 5 
CallWindowProc, 25 
Capabilities, devices, 183 
Caption, 26 
Caption bar, 28 
CAPTION statement, 294 
Capture. See Mouse capture 
Caret 

creating, 93 

destroying, 93 

displaying, 94 

flash rate, 95 

functions, 92 

hiding, 94 

moving, 94 

position, 94 
Carrier detect signal. See RLSD signal 
Catch, 195 
cBegin, 340 
cCall, 341 
CE_ DNS error, 231 
CE. FRAME error, 231 
CE_ IOE error, 231 
CE_ LOOP error, 231 
cEnd, 340 
CE_ OVERRUN error, 231 
CE_ PTO error, 231 
CE_ RXPARITY error, 231 
CF_ BITMAP format, 49, 51 
CF_ DIF format, 49, 51 
CF_ DSPMETAFILEPICT format, 50 
CF_ DSPTEXT format, 49 
OF_GDIOBJFIRST format, 50, 52 
CF_ GDIOBJLAST format, 50, 52 
CF_ METAFILEPICT format, 49, 51 
CF_ OWNERDISPLAY format, 49, 51 
CF_PRIVATEFIRST format, 50, 52 
CF_ PRIVATELAST format, 50, 52 
CF_SYLK format, 49, 51 
CF_ TEXT format, 49, 51 
ChangeClipboardChain, 55 
ChangeMenu, 62 
ChangeMenu flags, 64, 65 
char type, 251 
Character set, 263, 269 
Check box control, 297 
CHECKBOX statement, 297 
CheckDlgButton, 45 


CheckMenultem, 65 
CheckRadioButton, 46 
Child windows. See also Windows, 
child 
clipping, 29 
containing specified point, 96 
creation function, 27 
enumerating, 38 
ChildWindowFromPoint, 96 
Class. See Windows, class 
CLASS statement, 295 
Clear To Send signal, 274, 276 
ClearCommBreak, 233 
Client area, 85 
Client coordinates 
converting to screen coordinates, 95 
defined, 95 
final translation origin, 187 
identifying parent window, 96 
retrieving, 85 
ClientToScreen, 95 
Clipboard 
closing, 47 
counting formats, 53 
emptying, 48 
enumerating formats, 53 
functions, 47 
messages, 381 
opening, 47 
registering formats, 52 
retrieving data, 51 
retrieving format names, 53 
retrieving owner handle, 48 
setting data handles, 48 
viewer chain, 54, 55 
Clipboard formats. See Formats 
CLIPCAPS capability, 184 
ClipCursor, 91 
Clipping precision, 263 
Clipping region 
checking contents, 161 
child windows, 29 
combining, 162 
default, 71 
described, 159 
modifying, 159, 160 
retrieving, 159 
selecting, 139 
CloseClipboard, 47 
CloseComm, 226 
CloseMetaFile, 169 


CloseSound, 235 
Close Window, 35 
CLRDTR function code, 234 
CLRRTS function code, 234 
Cmacros 

Arg, 342 

assumes, 333 

calling convention, 329 

calls, 341 

cBegin, 340 

cCall, 341 

cEnd, 340 

codeOF FSET, 333 

cProc, 337 

createSeg, 331 

dataOF FSET, 333 

defined, 327 

DefX, 343 

errn}, 346 

errnz, 345 

Errors, 345 

example, 346, 347 

externX, 336 

FarPtr, 344 

functions, 337 

globalX, 335 

include file, 327 

labelX, 336 

LocalX, 339 

memory model option, 328 

overriding types, 346 

parmX, 338 

?PLM, 329 

RegPtr, 344 

Save, 342 

sBegin, 332 

segments, 331 

segNameOFFSET, 334 

sHnd, 332 

special definitions, 343 

stack checking option, 330 

staticX, 334 

storage allocation, 334 

symbol redefinition, 347 

?WIN, 330 

Windows prolog/epilog, 330 
CMACROS.INC file, 327 
CODE statement, 313 
codeOFFSET macro, 333 


Index 


COLOR_ ACTIVECAPTION index, 


102, 256 
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Color 
approximating, 187 
background, 142, 143 
flood fill operation, 124 
planes, 265 
table 
default, 71 
setting, 144 
RGB values, 244, 267 
setting in WIN.INI, 321 
system 
retrieving, 101 
WM_ SYSCOLORCHANGE 
message, 386 
system, setting, 102 
text, 144 
COLOR_ ACTIVECAPTION index, 
102, 256 
COLOR. BACKGROUND index, 102, 
256 
COLOR_ CAPTIONTEXT index, 102, 
256 
COLOR_ INACTIVECAPTION index, 
102, 256 
COLOR_ MENU index, 102, 256 
COLOR_ MENUTEXT index, 102, 256 
COLORONCOLOR mode, 147 
COLOR_ SCROLLBAR index, 102, 256 
COLOR_ WINDOW index, 102, 256 
COLOR_ WINDOWFRAME index, 
102, 256 
COLOR_ WINDOWTEXT index, 102, 
256 
CombineRgn, 162 
Communication device status. See 
COMSTAT data structure 
Communications 
baud rate, 273 
binary mode, 274 
bits per character, 273 
break control, 233 
break state, 233 
closing, 226 
CTS signal, 274, 276 
data structures, 272 
default configuration, 225 
delay, 276 
described, 225 
device control block, 228, 229 
device state, 229 
DSR signal, 274, 276 
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Communications (continued) 
DTR signal, 274, 275 
end-of-data character, 276, 277 
errors, 229 
errors reading, 227 
event mask, 231, 232 
events, 275, 276 
extended functions, 234 
flushing queue, 233 
null characters, 275 
opening, 225 
parity, 273, 274, 275 
reading, 227 
RLSD signal, 274, 276 
RTS signal, 274, 275 
stop bits, 273 
transmit characters, 228 
transmit immediate, 277 
writing, 227 
XON/XOFF flow control, 274, 275, 

276 

COMPLEXREGION code, 140, 159 

COMSTAT data structure, 276 

Control classes, 300, 301 

Control messages, 388 

CONTROL statement, 299 

Control statements 
CHECKBOX, 297 
CONTROL, 299 
CTEXT, 296 
DEFPUSHBUTTON, 298 
EDITTEXT, 298 
general form, 295 
GROUPBOX, 297 
ICON, 299 
LISTBOX, 297 
LTEXT, 296 
PUSHBUTTON, 297 
RADIOBUTTON, 298 
RTEXT, 296 

Control styles 
all classes, 306 
BUTTON, 302 
EDIT, 302 
LISTBOX, 304 
SCROLLBAR, 305 
STATIC, 304 

Control, yielding, 13, 206 

Controls 
check box, 297 
default push button, 298 


Controls (continued) 

edit, 298 

group box, 297 

icon, 299 

input to, 360 

list box, 297 

painting, 358 

push button, 297 

radio button, 298 

size box, 301 

text, 296 

user-defined, 299 
Conversions 

device to logical, 188 

display context, 187 

high-order byte, 242 

high-order word, 243 

integer to long pointer, 243 

integers, 242 

logical to device, 188 

long to POINT, 244 

lower to upper case, 218 

low-order byte, 242 

low-order word, 243 

mapping mode, 148 

OEM to ANSI, 218 

strings, 217 

upper to lower case, 218 

word to long, 243 
Coordinates 

functions, 95 

mapping mode, 148 
CopyMetaF ile, 170 
CopyRect, 97 
CountClipboardFormats, 53 
CountVoiceNotes, 241 
cProc macro, 337 
CreateBitmap, 131 
CreateBitmapIndirect, 132 
CreateBrushIndirect, 131 
CreateCaret, 93 
CreateCompatibleBitmap, 132 
CreateCompatibleDC, 108 
CreateDC, 107 
CreateDialog, 39 
CreateEllipticRgn, 164 
CreateEllipticRgnIndirect, 164 
CreateF ont, 134 
CreateFontIndirect, 137 
CreateHatchBrush, 130 
CreatelC, 108 
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CreateMenu, 62 
CreateMetaF ile, 169 
CreatePatternBrush, 130 
CreatePen, 128 
CreatePenIndirect, 129 
CreatePolygonRgn, 164 
CreateRectRgn, 163 
CreateRectRgnIndirect, 164 
createSeg macro, 331 
CreateSolidBrush, 129 
CREATESTRUCT data structure, 258 
CreateWindow, 26 
CS_ CLASSDC style, 72, 255 
CS_ DBLCLKS style, 254 
CS_ HREDRAW style, 254 
CS_ KEYCVTWINDOW style, 254 
CS_ OEMCHARS style, 254 
CS_ OWNDC style, 255 
CS_ VREDRAW style, 254 
CTEXT statement, 296 
CTL_ BTN code, 358 
CTL_ DLG code, 358 
CTL_ EDIT code, 358 
CTL_ LISTBOX code, 358 
CTL MSGBOX code, 358 
CTL_ SCROLLBAR code, 358 
CTL_ STATIC code, 358 
OTS signal, 274, 276 
Current position, 110, 111 
CURSOR resource, 282 
Cursor 

blink rate, 320 

class, 255 

defined, 90 

display count, 92 

displaying, 92 

hiding, 92 

loading, 209 

position, 91, 92 

predefined, 209 

shape, 91 
CURVECAPS capability, 184 


Data formats. See Formats 

Data Interchange Format. See DIF 
format 

Data interchange. See Clipboard 
functions 

Data Set Ready signal, 274, 276 

DATA statement, 314 
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Data structures 
BITMAP, 265 
COMSTAT, 276 
CREATESTRUCT, 258 
DCB, 272 
GDI, 259 
LOGBRUSH, 260 
LOGFONT, 261 
LOGPEN, 259 
METAFILEPICT, 271 
MSG, 257 
OFSTRUCT, 277 
PAINTSTRUCT, 257 
POINT, 266 
RECT, 266 
TEXTMETRIC, 267 
WNDCLASS, 254 
Data Terminal Ready signal, 274, 275 
Data types, naming conventions, 4 
dataOF FSET macro, 333 
DC. See Display context 
DCB data structure, 272 
DEF file. See Module definition file 
Default output device, 320 
Default push button control, 298 
Default window function, 21 
DEFAULT_ PITCH, 264 
DEFAULT_ QUALITY, 263 
# define directive, 308 
DEFPUSHBUTTON statement, 298 
DefWindowProc, 21 
DefX, 343 
DeleteAtom, 220 
DeleteDC, 109 
DeleteMetaF ile, 170 
DeleteObject, 138 
Descent, 268 
DESCRIPTION statement, 312 
DestroyCaret, 93 
DestroyMenu, 62 
Destroy Window, 30 
Device capabilities, 183 
Device control block. See DCB data 
structure 
Device drivers 
ABORTDOC escape, 176 
aspect ratio, 184 
brushes, 184 
capabilities, 183 
character-stream, PLP 183 
clipping capabilities, 184 
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Device drivers (continued) 
color bits per pixels, 184 
color planes, 184 
colors, 184 
curve capabilities, 184 
display-file 183 
DRAFTMODE escape, 177 
environment, 186 
ENDDOC escape, 173 
escape functions, 171 
FLUSHOUTPUT escape, 179 
fonts, 184 
GETCOLORTABLE escape, 178 
GETPHYSPAGESIZE escape, 178 
GETPRINTINGOFFSET escape, 
178 
GETSCALINGFACTOR escape, 179 
height in pixels, 184 
information, 180 
line capabilities, 185 
metafile, VDM 183 
NEWFRAME escape, 174 
NEXTBAND escape, 174 
pens, 184 
physical data, 184 
physical height, 183 
physical width, 183 
polygonal capabilities, 185 
QUERYESCSUPPORT escape, 179 
raster camera 183 
raster capabilities, 184 
raster display, 183 
raster printer 183 
SETABORTPROC escape, 175 
SETCOLORTABLE escape, 177 
STARTDOC escape, 172 
supported escape codes, 179 
technology, 183 
text capabilities, 185 
vector plotter, 183 
version number, 183 
width in pixels, 183 
Device mode settings, 386 
DEVICE_ DEFAULT FONT object, 
128 
Dialog box 
coordinates, 47 
dialog item. See Dialog item 
functions, 39 
initializing, 363 
list box 


list box (continued) 
creating, 41 | 
selection, 43 
modal 
creating, 40 
destroying, 41 
modeless 
creating, 39 
messages, 40 
units, 295 
Dialog item 
handle, retrieving, 43 
integer 
retrieving, 44 
setting, 43 
messages, 46 
text 
retrieving, 45 
setting, 44 
DIALOG resource 
CAPTION statement, 294 
CLASS statement, 295 
creating, 292 
control statements, 295 
dialog option statements, 293 
MENU statement, 294 
STYLE statement, 293 
DIALOG statement. See DIALOG 
resource 
DialogBox, 40 
DIF format, 47, 49, 51 
Directives 
# define, 308 
# elif, 309 
# else, 310 
# endif, 310 
# if, 309 
# ifdef, 308 
# ifndef, 309 
# include, 307 
# undef, 308 
DispatchMessage, 17 
Display context 
attributes, 140 
background color, 142, 143 
background mode, 143, 144 
clipping region, 159 
conversions, 187 
creating, 107 
current position, 111 
default attributes, 141 
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Display context (continued) 
default characteristics, 71 
deleting, 109 
device capabilities, 183 
device environment, 186 
drawing, 110 
drawing mode, 144, 145 
final translation origin, 187 
information, 180 
information context, 108 
intercharacter spacing, 167 
mapping mode, 148, 151 
memory display, 108 
polygon filling mode, 147, 148 
relabs flag, 142 
releasing, 73 
restoring, 110 
retrieving, 70 

for entire window, 72 
saving, 109 
selected objects, 138 
stock objects, 127 
stretching mode, 146, 147 
text color, 144 
viewport, 153, 154, 155, 156, 158 
window, 151, 152, 153, 154, 155 

Display count, 92 

Display device 
compatible memory displays, 108 

Display format 
bitmap, 49, 51 
metafile picture, 50, 51 
text, 49, 51 

DKGRAY_ BRUSH object, 127 

DigDirList, 41 

DigDirSelect, 43 

DLG_ HASSETSEL code, 360 

DLG_ WANTALLKEYS code, 360 

DLG_ WANTARROWS code, 360 

DLG_ WANTTAB code, 360 

Double click speed, 320 

DPtoLP, 188 

DRAFTMODE escape, 177 

DRAFT_ QUALITY, 263 

Drawlcon, 122 

Drawing modes 
default, 71 
list of, 270 
retrieving, 145 
setting, 144 

Drawing, described, 110 
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DrawMenuBar, 65 
DrawText, 119 
DRIVERVERSION capability, 183 
DSR signal, 274, 276 
DS_SYSMODAL, 294 
DTR signal, 274, 275 
DWORD type, 251 
Dynamic linking 

code, 192 

data segments, 193, 194 

described, 191 


Edit control 

creating, 298 

messages, 390 

notification codes, 401 
EDIT control class, 300 
EDIT control styles, 302 
EDITTEXT statement, 298 
# elif directive, 309 
Ellipses, drawing, 113 
Elliptical arcs, 114 
# else directive, 310 
EM_CANUNDO message, 395 
EM_FMTLINES message, 396 
EM_ GETHANDLE message, 392 
EM_ GETLINE message, 394 
EM_ GETLINECOUNT message, 392 
EM_ GETRECT message, 390 
EM_ GETSEL message, 390 
EM_ GETTHUMB message, 393 
EM_ LIMITTEXT message, 395 
EM_ LINEINDEX message, 392 
EM_ LINELENGTH message, 394 
EM_ LINESCROLL message, 393 
EmptyClipboard, 48 
EM_ REPLACESEL message, 394 
EM_SCROLL message, 393 
EM_SETFONT message, 394 
EHM_SETHANDLE message, 391 
EM_SETRECT message, 391 
EM_SETRECTNP message, 391 
EM_SETSEL message, 390 
EM_ UNDO message, 395 
EnableMenultem, 66 
EnableWindow, 60 
EN CHANGE code, 401 
EndDialog, 41 
ENDDOC escape, 173 
# endif directive, 310 
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End-of-data character, 276, 277 

EndPaint, 74 

EN_ ERRSPACE code, 401 

English units, 149 

EN HSCROLL code, 402 

EN_ KILLFOCUS code, 401 

EN_ SETFOCUS code, 401 

Entry point, main function, 9 

EnumChild Windows, 38 

EnumClipboardFormats, 53 

EnumFonts, 180 

EnumObjects, 181 

EnumProps, 83 

EnumWindows, 37 

EN_ VSCROLL code, 402 

EqualRgn, 163 

errn}, 346 

errnz, 345 

ERROR code, 140, 159 

Error functions, 87 

Errors, 225 

ES_ AUTOHSCROLL style, 303 

ES_ AUTOVSCROLL style, 303 

Escape, 171, 172, 173, 174, 175, 176, 
177, 178, 179 

EscapeCommF unction, 234 

Escapement, 262 

ES_ CENTER style, 302 

ES_ LEF'T style, 302 

ES_ MULTILINE style, 303 

ES_ NOHIDESEL style, 303 

ES_ RIGHT style, 302 

EV_ BREAK event, 231, 232 

EV_ CTS event, 231, 232 

EV_ DSR event, 231, 232 

EVENPARITY, 273 

EV_ERR event, 231, 232 

EV_ PERR event, 231 

EHV_ RING event, 231 

EV_RLSD event, .231, 232 

EV_RXCHAR event, 231, 232 

EV_RXFLAG event, 231, 232 

EV_ TXEMPTY event, 231, 232 

ExcludeClipRect, 160 

Execution, terminating, 10 

EXPORTS statement, 316 

Extents, 71 

extern X macro, 336 


Face name, 264 


Far pointer, 6 
FAR type, 252 
FARPROC type, 252 
FarPtr, 344 
FatalExit, 225 
FF_ DECORATIVE family, 264, 427 
FF_DONTCARE family, 264, 427 
FF_ MODERN family, 264, 427 
FF_ ROMAN family, 264, 427 
FF_ SCRIPT family, 264, 427 
FF_SWISS family, 264, 427 
File attributes, 42 
File formats 
font files, 425 
module definition file, 311 
raster fonts, 430 
resource file, 281 
vector fonts, 431 
Files 
described, 245 
initialization, 222 
opening, 245 
temporary, 246 
temporary drive, 248 
FillRect, 126 
FillRgn, 125 
Final translation origin, 187 
FindAtom, 221 
FindResource, 212 
Find Window, 85 
FIXED_ PITCH, 264 
Flash rate. See Caret, flash rate 
Flash Window, 90 
FloodFill, 124 
FlushComm, 233 
FLUSHOUTPUT escape, 179 
Focus. See Input, focus 
Font files, 425 
FONT resource, 282 
Fonts 
adding, 207, 386 
creating, 134, 137 
default, 71 
deleting, 138 
enumerating, 180 
logical, 261, 262, 263, 264 
physical, 267, 268, 269 
reference count, 208 
removing, 208, 386 
retrieving, 140 
selecting, 138 
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Fonts (continued) 

stock, 127 

text color, 144 

text metrics, 183 

WIN.INI, 323 
Formats, 47, 52, 53 
FrameRect, 126 
FrameRgn, 125 
FreeLibrary, 194 
FreeProcInstance, 194 
F'reeResource, 215 
Function macros, 337 
Functions 

naming conventions, 4 

notational conventions, 3 


GCL_ MENUNAMEH index, 23, 24 
GCL_ WNDPROC index, 23, 24 
GCW_ CBCLSEXTRA index, 23, 24 
GCW_ CBWNDEXTRA index, 23, 24 
GCW_HBRBACKGROUND index, 23, 
24 

GCW_HCURSOR index, 23, 24 
GCW_ HICON index, 23, 24 
GCW_ HINSTANCE index, 23, 24 
GCW_ STYLE index, 23, 24 
GDI 

data structures, 259 

functions, 107 
GetAtomName, 221 
GetBitmapBits, 133 
GetBitmapDimension, 134 
GetBkColor, 143 
GetBkMode, 144 
GetBrushOrg, 158 
GetBValue, 244 
GetCaretBlink Time, 95 
GetClassLong, 23 
GetClassName, 22 
GetClass Word, 23 
GetClientRect, 85 
GetClipboardData, 51 
GetClipboardFormatName, 53 
GetClipboardOwner, 48 
GetClipboard Viewer, 54 
GetClipBox, 159 
GetCodeHandle, 193 
GETCOLORTABLE escape, 178 
GetCommeError, 229 
GetCommEventMask, 232 
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GetCommState, 229 
GetCurrentPosition, 111 
GetCurrent Task, 206 
GetCurrent Time, 15 
GetCursorPos, 92 
GetDC, 70 

GetDCOrg, 187 
GetDeviceCaps, 183 
GetDlgItem, 43 
GetDlgItemInt, 44 
GetDigItemText, 45 
GetEnvironment, 186 
GetFocus, 56 
GetGValue, 244 
GetInstanceData, 192 
GetKeyState, 56 
GetMapMode, 151 
GetMenu, 62 
GetMenuString, 69 
GetMessage, 10 
GetMessagePos, 14 
GetMessageTime, 14 
GetMetaFile, 169 
GetMetaF ileBits, 170 
GetModuleFileName, 191 
GetModuleHandle, 191 
GetModuleUsage, 191 
GetNearestColor, 187 
GetObject, 140 
GetParent, 85 
GETPHYSPAGESIZE escape, 178 
GetPixel, 123 
GetPolyFillMode, 148 
GETPRINTINGOFFSET escape, 178 
GetProcAddress, 192 
GetProfileInt, 222 
GetProfileString, 223 
GetProp, 82 

GetRelAbs, 142 
GetROP2, 145 
GetRValue, 244 
GETSCALINGFACTOR escape, 179 
GetScrollPos, 79 
GetScrollRange, 81 
GetStockObject, 127 
GetStretchBltMode, 147 
GetSubMenu, 68 
GetSysColor, 101 
GetSysModalWindow, 86 
GetSystemMenu, 68 
GetSystemMetrics, 100 
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GetTempDrive, 248 

GetTempFileName, 246 

Get TextCharacterExtra, 167 

Get TextColor, 144 

Get TextExtent, 166 

Get TextFace, 182 

GetTextMetrics, 183 

Get ThresholdEvent, 241 

Get ThresholdStatus, 241 

GetUpdateRect, 75 

Get Version, 195 

Get ViewportExt, 158 

Get ViewportOrg, 154 

GetWindowDC, 72 

GetWindowExt, 153 

GetWindowLong, 31 

GetWindowOrg, 151 

GetWindowRect, 86 

GetWindowText, 84 

GetWindowTextLength, 84 

Get WindowWord, 30 

GlobalAlloc, 196 

GlobalCompact, 197 

GlobalDiscard, 197 

GlobalF lags, 200 

GlobalF ree, 197 

GLOBALHANDLE type, 253 

GlobalLock, 198 

GlobalReAlloc, 198 

GlobalSize, 199 

GlobalUnlock, 200 

globalX macro, 335 

GMEM_ DISCARDABLE flag, 196, 199, 
200 

GMEM_ DISCARDED flag, 200 

GMEM_ FIXED flag, 196, 198 

GMEM_ LOCKCOUNT flag, 200 

GMEM_ MODIFY flag, 199 

GMEM_ MOVEABLE flag, 196, 198 

GMEM_ NOCOMPACT flag, 196, 199 

GMEM_ NODISCARD flag, 196, 199 

GMEM_ SWAPPED flag, 200 

GMEM_ ZEROINIT flag, 196, 199 

Graphic Device Interface, 107. See also 
GDI 


Graphs, connected lines, 111 
GRAY_ BRUSH object, 127 
GrayString, 121 

Group box control, 297 
GROUPBOX statement, 297 
GWL_ STYLE index, 31, 32 


GWL_ WNDPROC index, 31, 32 
GWW_ HINSTANCE index, 30, 31 
GWW_HWNDPARENT index, 30, 31 
GWW_HWNDTEXT index, 30, 31 
GWW-_ ID index, 30, 31 


HANDLE type, 252 

Handle types, 252 

Hatch style, 261 

HBITMAP type, 253 

HBRUSH type, 253 

HCURSOR type, 253 

HDC type, 253 

Heap 

global 
allocating, 196 
compacting, 197 
condition flags, 200 
described, 196 
discarding, 197 
freeing, 197 
locking, 198 
reallocating, 198 
size, 199 
unlocking, 200 
local 

allocating, 200 
compacting, 201, 202, 203 
condition flags, 206 
data segment, 205 
described, 196 
discarding, 202 
freeing, 202 
freezing, 202 
handle delta, 205 
handle table, 205 
locking, 202 
locking data segment, 205 
melting, 203 
reallocating, 203 
size, 204 
unlocking, 205 

HEAPSIZE statement, 312 

HFONT type, 253 

HIBYTE, 242 

HICON type, 253 

HideCaret, 94 

HIDE_ WINDOW flag, 33 

HiliteMenultem, 67 

HIWORD, 243 
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HMENU type, 253 

HOLLOW_ BRUSH object, 127 
Hook, 103 

HORZRES capability, 183 
HORZSIZE capability, 183 

HPEN type, 253 

HRGN type, 253 

HS_ BDIAGONAL hatch style, 261 
HS_ CROSS hatch style, 261 

HS_ DIAGCROSS hatch style, 261 
HS_ FDIAGONAL hatch style, 261 
HS_ HORIZONTAL hatch style, 261 
HSTR type, 252 

HS_ VERTICAL hatch style, 261 
HTCAPTION code, 404 
HTCLIENT code, 404 

HTERROR code, 404 
HTGROWBOX code, 404 
HTHSCROLL code, 404 
HTMENU code, 404 
HTNOWHERE code, 404 
HTSYSMENU code, 404 
HTTRANSPARENT code, 404 
HTVSCROLL code, 404 


Icon control, 299 
ICON resource, 282 
ICON statement, 299 
Icons 

class, 255 

drawing, 122 

loading, 210 

opening, 34 

predefined, 210 
IDABORT code, 89 
IDCANCEL code, 89 
IDC_ ARROW cursor code, 210 
IDC_ CROSS cursor code, 210 
IDC_ IBEAM cursor code, 210 
IDC_ ICON cursor code, 210 
IDC_ SIZE cursor code, 210 
IDC_ UPARROW cursor code, 210 
IDC_ WAIT cursor code, 210 
IDI APPLICATION icon code, 211 
IDL ASTERISK icon code, 211 
IDI. EXCLAMATION icon code, 211 
IDIGNORE code, 89 
IDI_ HAND icon code, 211 
IDI_ QUESTION icon code, 211 
IDNO code, 89 
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IDOK code, 89 
IDRETRY code, 89 
IDYES code, 89 
IK BADID error, 226 
IE_ BAUDRATE error, 226 
IE_ BY TESIZE error, 226 
IE_ DEFAULT error, 226 
IE_ HARDWARE error, 226 
[E_ MEMORY error, 226 
IE_ NOPEN error, 226 
IE OPEN error, 226 
# if directive, 309 
# ifdef directive, 308 
# ifndef directive, 309 
IMPORTS statement, 317 
# include directive, 307 
InflateRect, 98 
Information context, 108, 109 
InitAtomTable, 219 
Initialization 
file, 318 
functions, 222, 223, 224 
messages, 362 
strings, 223 
Input 
disabling, 60 
enabling, 60, 61 
focus 
acquiring, 56 
described, 55 
identifying window, 56 
messages, 353 
functions, 55 
messages, 364 
Instances 
data, 192 
described, 191 
functions, 193, 194 
int type, 251 
Integer messages, 351 
Intercharacter spacing, 71, 167 
IntersectClipRect, 159 
IntersectRect, 98 
InvalidateRect, 75 
InvalidateRgn, 76 
InvertRect, 127 
InvertRgn, 126 
IsDialogMessage, 40 
IsDlgButtonChecked, 45 
IsIconic, 37 
IsRectEmpty, 99 
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IsWindow, 29 
IsWindowEnabled, 61 
IsWindowVisible, 36 
Italic font, 262 


Justification, 165 


Kerning, 167 

Key codes, 419 

Key state. See Virtual keys, state 
KEYLAST code, 12 

KillTimer, 60 


labelX macro, 336 
LB_ ADDSTRING message, 397 
LB_ DELETESTRING message, 398 
LB_ DIR message, 400 
LB_ GETCOUNT message, 400 
LB_ GETCURSEL message, 399 
LB_ GETSEL message, 399 
LB_ GETTEXT message, 399 
LB_ GETTEXTLEN message, 399 
LB_INSERTSTRING message, 397 
LBN_DBLCLK code, 402 
LBN_ ERRSPACE code, 402 
LBN_ SELCHANGE code, 402 
LB_SELECTSTRING message, 400 
LB_SETCURSEL message, 398 
LB_SETSEL message, 398 
LBS_ MULTIPLESEL style, 304 
LBS_ NOREDRAW style, 304 
LBS_ NOTIFY style, 304 
LBS_ SORT style, 304 
Leading, 268 
Libraries, 194 
LIBRARY statement, 312 
LINECAPS capability, 185 
LineDDA, 124 
LineTo, 111 
Linking 

described, 191 

procedure addresses, 192 

procedure instances, 193, 194 
List box 

control, 297 

messages, 397 

notification codes, 402 


LISTBOX 


LISTBOX — 
control class, 300 
control styles, 304 
statement, 297 
LMEM_ DISCARDABLE flag, 201, 204, 
206 
LMEM_ DISCARDED flag, 206 
LMEM_ FLXED flag, 201, 203 
LMEM_ LOCKCOUNT flag, 206 
LMEM_ MODIFY flag, 204 
LMEM_ MOVEABLE flag, 201, 203 
LMEM_ NOCOMPACT flag, 201, 204 
LMEM_ NODISCARD flag, 201, 204 
LMEM_ ZEROINIT flag, 201, 204 
LoadAccelerators, 212 
LoadBitmap, 209 
LoadCursor, 209 
LoadIcon, 210 
LoadLibrary, 194 
LoadMenu, 211 
LoadResource, 214 
LoadString, 212 
LOBYTE, 242 
LocalAlloc, 200 
LocalCompact, 201 
LocalDiscard, 202 
LocalF lags, 206 
LocalF ree, 202 
LocalF reeze, 202 
LOCALHANDLE type, 253 
LocalHandleDelta, 205 
LocalLock, 202 
LocalMelt, 203 
LocalReAlloc, 203 
LocalSize, 204 
LocalUnlock, 205 
LocalX, 339 
LockData, 205 
LockResource, 214 
LOGBRUSH data structure, 260 
LOGFONT data structure, 261 
LOGPEN data structure, 259 
Long pointer, 6 
LONG type, 251 
LOWORD, 243 
LPINT type, 252 
LPMSG type, 252 
LPRECT type, 252 
LPSTR type, 252 
LPtoDP, 188 
LTEXT statement, 296 
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LTGRAY_ BRUSH object, 127 


Macros. See Cmacros 
Main function, 9 
MAKEINTATOM, 221 
MAKEINTRESOURCE, 243 
MAKELONG, 243 
MAKEPOINT, 244 
MakeProclInstance, 193 
MapDialogRect, 47 
Mapping mode 
default, 71 
retrieving, 151 
setting, 148 
units of measure, 148 
MARKPARITY, 273 
max, 245 
MB_ ABORTRETRYIGNORE code, 87 
MB_APPLMODAL code, 88 
MB_ DEFBUTTONI code, 88 
MB_DEFBUTTON2 code, 88 
MB_ DEFBUTTONS code, 88 
MB_ ICONASTERISK code, 88 
MB_ICONEXCLAMATION code, 88 
MB_ICONHAND code, 88 
MB_ ICONQUESTION code, 88 
MB_ OK code, 87 
MB_ OKCANCEL code, 87 
MB_ RETRYCANCEL code, 87 
MB_SYSTEMMODAL code, 88 
MB_ YESNO code, 87 
MB_ YESNOCANCEL code, 88 
Memory display, 108 
Memory 
compacting, 196, 197 
described, 196 
discardable, 196 
discarding, 197 
fixed, 196 . 
global 
allocation, 196 
described, 196 
flags, 200 
freeing, 197 
locking, 198 
reallocation, 198 
unlocking, 200 
heaps, 196 
initializing, 196 
local 
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local (continued) 
allocating, 200 
compacting, 201, 202, 203 
condition flags, 206 
data segment, 205 
described, 196 
discarding, 202 
freeing, 202 
freezing, 202 
handle delta, 205 
handle table, 205 
locking, 202 
locking data segment, 205 
melting, 203 
reallocating, 203 
size, 204 
unlocking, 205 
movable, 196 
reference count, 198, 200, 202, 205, 


size, 199 
MENU, 294 
Menu bar menu. See Top-level menu 
MENU resource, 287 
MENU statement, 294 
Menu 
bar, redrawing, 65 
changing, 62 
class, 256 
creating, 62 
destroying, 62 
functions, 61 
initializing, 362, 363 
item 
checking, 65 
disabling, 66 
enabling, 66 
graying, 66 
highlighting, 67 
label, retrieving, 69 
loading, 211 
popup 
defined, 61 
retrieving handle, 68 
retrieving handle, 62 
setting, 61 
system, 68 
top-level, 61 
window, 258 
MENUITEM SEPARATOR statement, 
291 


446 


MENUITEM statement, 288, 289 
Message box 
beep, 89 
creating, 87 
MessageBeep, 89 
MessageBox, 87 
Messages 
accelerator, 16 
BM_ GETCHECK, 388 
BM_ GETSTATE, 389 
BM_ SETCHECK, 389 
BM_ SETSTATE, 389 
checking for, 12 
clipboard, 381 
contents, 351 
control 
button, 388 
edit, 390 
list box, 397 
default processing, 21 
dispatching, 17 
EM_ CANUNDO, 395 
EM_FMTLINES, 396 
EM_ GETHANDLE, 392 
EM_ GETLINE, 394 
EM_ GETLINECOUNT, 392 
EM_ GETRECT, 390 
EM_ GETSEL, 390 
EM_ LIMITTEXT, 395 
EM_ LINEINDEX, 392 
EM_ LINELENGTH, 394 
EM_ LINESCROLL, 393 
EM_ REPLACESEL, 394 
EM_ SCROLL, 393 
EM_SETFONT, 394 
EM_ SETHANDLE, 391 
EM_ SETRECT, 391 
EM_ SETRECTNP, 391 
EM_SETSEL, 390 
EM_ UNDO, 395 
functions, 10 
initialization, 362 
input, 364 
integer, 351 
LB_ ADDSTRING, 397 
LB_ DELETESTRING, 398 
LB_ DIR, 400 
LB_ GETCOUNT, 400 
LB_ GETCURSEL, 399 
LB_ GETSEL, 399 
LB_ GETTEXT, 399 


Messages (continued 

LB_ GETTEXTLEN, 399 
LB_INSERTSTRING, 397 
LB_ SELECTSTRING, 400 
LB_ SETCURSEL, 398 
LB_SETSEL, 398 

mouse position, 14 

non-client area, 402 
notification, 401 

posting, 10, 18, 19 

processing, 20 

ranges, 351 

registering, 19 

replying to, 19 

reserved, 351 

retrieving, 10 

scroll bar, 402 

sending, 17, 18 

string, 351 

system, 377 

system information, 386 

time of, 14 

translating, 15, 16 

virtual key, 15 

waiting for, 13 

window management, 352 
WM_ ACTIVATE, 353 

WM_ ACTIVATEAPP, 354 
WM_ ASKCBFORMATNAMEB, 385 
WM_ CHANGECBCHAIN, 382 
WML_ CHAR, 372 

WM_ CLEAR, 397 

WML_ CLOSE, 361 

WM_ COMMAND, 374 

WML_ COPY, 396 

WM_ CREATE, 352 

WM_ CTLCOLOR, 358 

WM_ CUT, 396 

WM_ DEADCHAR, 373 

WM_ DESTROY, 361 

WM_ DESTROYCLIPBOARD, 382 
WM_ DEVMODECHANGE, 386 
WM_ DRAWCLIPBOARD, 382 
WM_ ENABLE, 353 
WM_ENDSESSION, 362 
WM_ ERASEBKGND, 357 
WM_ FONTCHANGE, 386 
WM_ GETDLGCODE, 360 
WM_ GETTEXT, 359 

WM_ GETTEXTLENGTH, 359 
WM_HSCROLL, 376 
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HSCROLLCLIPBOARD, 385 
WM. INITDIALOG, 363 
WM_INITMENU, 363 
WM_INITMENUPOPUP, 362 
WM_KEYDOWN, 370 
WM_KEYUP, 371 
WM_KILLFOCUS, 353 
WM_LBUTTONDBLCLK, 368 
WM_LBUTTONDOWN, 365 
WM_LBUTTONUP, 365 
WM_MBUTTONDBLCLK, 370 
WM_MBUTTONDOWN, 367 
WM_MBUTTONUP, 368 
WM_ MOUSEMOVE, 364 
WM_ MOVE, 357 
WM_NCACTIVATE, 405 
WM_NCCALCSIZE, 403 
WM_NCCREATE, 403 
WM_NCDESTROY, 403 
WM_NCHITTEST, 404 
WM_NCLBUTTONDBLCLK, 406 
WM_NCLBUTTONDOWN, 405 
WM_NCLBUTTONUP, 406 
WM_NCMBUTTONDBLCLK, 408 
WM_NCMBUTTONDOWN, 407 
WM_NCMBUTTONUP, 407 
WM_NCMOUSEMOVE, 405 
WM_NCPAINT, 405 
WM_NCRBUTTONDBLCLK, 407 
WM_NCRBUTTONDOWN, 406 
WM_NCRBUTTONUP, 407 
WM_ PAINT, 357 
WM_PAINTCLIPBOARD, 383 
WM_ PASTE, 397 
WM_ QUERYENDSESSION, 361 
WM_ QUERYOPEN, 352 
WM_ QUIT, 362 
WM_RBUTTONDBLCLK, 369 
WM_RBUTTONDOWN, 366 
WM_RBUTTONUP, 366 
WM_RENDERALLFORMATS, 382 
WM_RENDERFORMAT, 381 
WM_SETFOCUS, 353 
WM_SETREDRAW, 359 
WM_SETTEXT, 359 
WM_SETVISIBLE, 352 
WM_SHOWWINDOW, 355 
WM_ SIZE, 356 
WM_SIZECLIPBOARD, 383 
WM_SYSCHAR, 379 
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Messages (continued) 
WM_SYSCOLORCHANGE, 386 
WM_SYSCOMMAND, 380 
WM_SYSDEADCHAR, 380 
WM_SYSKEYDOWN, 377 
WM_SYSKEYUP, 378 
WM_SYSTEMERROR, 387 
WM_ TIMECHANGE, 387 
WM_ TIMER, 374 
WM_ USER, 351 
WM_ VSCROLL, 375 
WM_ VSCROLLCLIPBOARD, 384 
WM_ WININICHANGE, 387 

Metafile picture display format. See 

Display format 

Metafile picture format, 47, 49, 51, 271 

METAFILEPICT data structure, 271 

Metafiles 
closing, 169 
copying, 170 
creating, 169 
deleting, 170 
described, 168 
GDI restrictions, 168 
playing, 170 
retrieving, 169 
retrieving bits, 170 
setting bits, 171 

Metric units, 149 

MF_ APPEND menu flag, 64 

MF_ BITMAP menu flag, 64 

MF_ BYCOMMAND menu flag, 64, 66, 


67, 70 
MF_BYPOSITION menu flag, 64, 66, 
67, 70 
MF_ CHANGE menu flag, 64 
MF_ CHECKED menu flag, 64, 66 
MF_ DELETE menu flag, 64 
MF_ DISABLED menu flag, 64, 66 
MF_ ENABLED menu dag, 64, 66 
MF_ GRAYED menu flag, 64, 66 
MF_ HILITE menu flag, 67 
MF_ INSERT menu flag, 64 
MF_ MENUBARBREAK menu flag, 64 
MF__MENUBREAK menu flag, 64 
MF_ POPUP menu flag, 65 
MF_ SEPARATOR menu flag, 64 
MF_ STRING menu flag, 65 
MF_ UNCHECKED menu flag, 64, 66 
MF_ UNHILITE menu flag, 67 
min, 244 
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MK _ CONTROL, 364, 365, 366, 367, 
368, 369, 370 
MK LBUTTON, 364, 366, 367, 368, 
369, 370 
MK_ MBUTTON, 364, 365, 366, 367, 
368, 370 
MK _ RBUTTON, 364, 365, 367, 368, 
369, 370 
MK_ SHIFT, 364, 365, 366, 367, 368, 
369, 370 
MM_LOENGLISH mode, 149 
MM_ ANISOTROPIC mode, 150 
MM_ HIENGLISH mode, 149 
MM_ HIMETRIC mode, 149 
MM_ ISOTROPIC mode, 150 
MM_LOMETRIC mode, 149 
MM_ TEXT mode, 149 
MM_ TWIPS mode, 149 
Modal dialog box. See Dialog box 
Modeless dialog box. See Dialog box 
Module definition file 
CODE statement, 313 
DATA statement, 314 
DESCRIPTION statement, 312 
EXPORTS statement, 316 
HEAPSIZE statement, 312 
IMPORTS statement, 317 
LIBRARY statement, 312 
NAME statement, 311 
SEGMENT statement, 315 
STACKSIZE statement, 313 
STUB statement, 318 
Modules 191, 194 
Mouse capture, 55, 58 
Mouse cursor. See Cursor 
Mouse input, 58, 59 
MoveTo, 110 
MoveWindow, 35 
MS-DOS 
error codes, 194: 
file attributes, 42 
MSG data structure, 257 
MSGF_ DIALOGBOX code, 104 
MSGF_ MENU code, 104 
MSGF_ MESSAGEBOX code, 104 


NAME statement, 311 
Naming conventions, 4 
Near pointer, 6 


NEAR type, 252 


NEWFRAME escape, 174 
NEXTBAND escape, 174 
Non-client area messages, 402 
NOPARITY, 273 

NORMAL voice, 236 
Notational conventions, 3 
Notification codes, 401, 402 
Null port name, 320 

NULL_ BRUSH object, 128 
NULL_ PEN object, 128 
NULLREGION code, 140, 159 
NUMBRUSHES capability, 184 
NUMCOLORS capability, 184 
NUMFONTS capability, 184 
NUMPENS capability, 184 


Objects 

deleting, 138 

described, 127 

enumerating, 181 

retrieving, 140 

selecting, 138 

stock, 127 
ODDPARITY, 273 
OEM_ CHARSET, 263 
OEM_ FIXED _ FONT object, 128 
OemToAnsi, 218 
OF_ CANCEL file style, 246 
OF_ CREATE file style, 245 
OF_ DELETE file style, 246 
OF_ EXIST file style, 245 
OffsetClipRgn, 160 
OffsetRect, 99 
OffsetRgn, 163 
Offset ViewportOrg, 156 
Offset WindowOrg, 155 
OF_ PROMPT file style, 246 
OF_ READ file style, 245 
OF_READWRITE file style, 245 
OF_ REOPEN file style, 245 
OFSTRUCT data structure, 245, 277 
OF_ VERIFY file style, 246 
OF_ WRITE file style, 245 
ONES5STOPBITS, 273 
ONESTOPBIT, 273 
OPAQUE mode, 142, 143 
Open file data structure, 277 
OpenClipboard, 47 
OpenComm, 225 
OpenFile, 245 
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Openlcon, 34 
OpenSound, 235 
Origin 

brush, 71 

viewport, 71 

window, 71 
Output devices, 320, 322 
Output precision, 263 
Output quality, 263 
Overhang, 269 
Owner display format, 49, 51 


Painting 
completing, 74 
functions, 70 
invalidating 
rectangle, 75 
region, 76 
preparation for, 73 
validating 
rectangle, 76 
region, 77 
PaintRgn, 126 
PAINTSTRUCT data structure, 257 
Parent window. See Windows, parent 
Parity, 273, 274, 275 
parmX macro, 338 
Pascal calling convention, 5 
PatBlt, 115 
PDEVICESIZE capability, 184 
PeekMessage, 12 
Pens 
color, 260 
creating, 128, 129 
default, 71 
deleting, 138 
enumerating, 181 
retrieving, 140 
selecting, 138 
stock, 127 
style, 128, 260 
width, 260 
Pies, drawing, 115 
PINT type, 252 
Pitch, 264 
Pixels, 123 
PLANES capability, 184 
Planes. See Color, planes 
PlayMetaF ile, 170 
?PLM, 329 
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POINT data structure, 244, 266 
Pointers 

size, 6 

types, 252 
POLYGONALCAPS capability, 185 
Polygons 

drawing, 111, 113 

filling mode, 71, 113, 147 
Polyline, 111 
Popup menu. See Menu, popup 
POPUP statement, 288, 290 
Popup windows. See Windows, popup 
Ports, 321 
PostAppMessage, 19 
PostMessage, 18 
PostQuitMessage, 10 
Printing, 173 
PROOF_ QUALITY, 263 
Property list, 81, 82, 83 
PSTR type, 252 
PtInRect, 99 
PtInRegion, 165 
PtVisible, 161 
Push button control, 297 
PUSHBUTTON statement, 297 


QUERYESCSUPPORT escape, 179 


Radio button control, 298 
RADIOBUTTON statement, 298 
Raster fonts, 430 
Raster operation codes, 145, 270, 411 
RASTERCAPS capability, 184 
RC_ BANDING capability, 184 
RC_BITBLT capability, 184 
RC_ SCALING capability, 184 
ReadComm, 227 
Ready To Send signal, 275 
Receive Line Signal Detect signal, 276 
RECT data structure 

copying, 97 

defined, 266 

empty, 97, 99 

filling, 97 
Rectangles 

client, 85 

containing point, 99 

copying, 97 

data structure, 266 
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Rectangles (continued) 
drawing, 112 
empty, 97, 99 
expanding, 98 
filled, 126 
framed (border), 126 
functions, 97 
intersecting, 98 
invalidating, 75 
inverting (highlighting), 127 
offsetting, 99 
rounded corners, 112 
shrinking, 98 
union, 98 
updating, 75 
validating, 76 
window, 86 
Rect Visible, 161 
Redraw flag, 359 
Regions 
checking contents, 165 
comparing, 163 
creating elliptic, 164 
creating polygons, 164 
creating rectangles, 163, 164 
deleting, 138 
described, 162 
filled, 125 
framed (border), 125 
invalidating, 76 
inverting (highlighting), 126 
moving, 163 
painting, 126 
selecting, 138 
validating, 77 
RegisterClass, 22 
RegisterClipboardFormat, 52 
Registering 
formats, 52 
messages, 19 
window class, 22 
Register WindowMessage, 19 
RegPtr, 344 
Relabs flag, 71, 142 
RELATIVE mode, 142 
ReleaseCapture, 59 
ReleaseDC, 73 
RemoveFontResource, 208 
RemoveProp, 82 
ReplyMessage, 19 
Request To Send signal, 274 


Reserved messages, 351 
RESETDEV function code, 234 
Resource directives. See Directives 
Resource file, 281 
Resource statements, 282 
Resources 

accelerators, 212, 286 

accessing, 215 

allocating space, 214 

bitmaps, 209, 282 

cursors, 209, 282 

DIALOG, 292 

finding, 212 

font, 207, 208, 282 

freeing, 215 

functions, 207 

handler, 216 

icons, 210, 282 

integer ID, 213 

loading, 214 

locking, 214 

menus, 211, 287 

reference count, 214, 215 

size, 216 

strings, 212, 284 

user-defined, 283 
RestoreDC, 110 
Revision number, 195 
RGB color value, 267 
RLSD signal, 274, 276 
Rops. See Raster operation codes 
RoundRect, 112 
RT_ ACCELERATOR resource code, 

213 

RT_ BITMAP resource code, 213 
RT_ CURSOR resource code, 213 
RT_ DIALOG resource code, 213 
RTEXT statement, 296 
RT_ FONT resource code, 213 
RT_ICON resource code, 213 
RT_ MENU resource code, 213 
RTS signal, 274, 275 
RT_ STRING resource code, 213 


S_ALLTHRESHOLD state, 240 
Save, 342 
SaveDC, 109 


SB_ BOTTOM code, 375, 376, 384, 385 


SB_ CTL code, 79, 80, 81 
sBegin macro, 332 
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SB_ ENDSCROLL code, 375, 376, 384, 
385 
SB_ HORZ code, 79, 80, 81 
SB_ LINEDOWN code, 375, 376, 384, 
385, 393 
SB_ LINEUP code, 375, 376, 384, 385, 
393 
SB. PAGEDOWN code, 375, 376, 384, 
385, 393 
SB_ PAGEUP code, 375, 376, 384, 385, 
393 
SBS_ BOTTOMALIGN style, 305 
SBS_ HORZ style, 305 
SBS_ LEFTALIGN style, 305 
SBS_ RIGHTALIGN style, 305 
SBS_ SIZEBOX style, 305 
SBS_ SIZEBOXBOTTOMRIGHTALIGN 
style, 306 
SBS_ SIZEBOXTOPLEFTALIGN 
style, 306 
SBS_ TOPALIGN style, 305 
SBS_ VERT style, 305 
SB_ THUMBPOSITION code, 375, 376, 
384, 385, 393 
SB_ THUMBTRACK code, 375, 376 
SB_ TOP code, 375, 376, 384, 385 
SB_ VERT code, 79, 80, 81 
Scale ViewportExt, 155 
ScaleWindowExt, 154 
SC_ CLOSE command, 69, 380 
SC_ HSCROLL command, 69, 380 
SC_ ICON command, 69, 380 
SC_ KEYMENU command, 69, 380 
SC_ MOUSEMENU command, 69, 380 
SC_ MOVE command, 69, 380 
SC_ NEXTWINDOW command, 69, 
380 
SC_PREVWINDOW command, 89, 
380 
Screen coordinates, 95, 96 
Screen ToClient, 96 
Scroll bar 
adding, 80 
horizontal, 28 
messages, 402 
position, 79 
range, 80, 81 
removing, 80 
vertical, 28 
SCROLLBAR control class, 301 
SCROLLBAR control styles, 305 
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Scrolling functions, 77 
ScrollWindow, 77 

SC_ SIZE command, 69, 380 
SC_ VSCROLL command, 69, 380 
SC_ ZOOM command, 69, 380 
SEGMENT statement, 315 
segNameOFFSET, 334 
SelectClipRgn, 139 
SelectObject, 138 

sEnd macro, 332 
SendDlgItemMessage, 46 
SendMessage, 17 
SETABORTPROC escape, 175 
SetActive Window, 36 
SetBitmapBits, 133 
SetBitmapDimension, 133 
SetBkColor, 142 
SetBkMode, 143 
SetBrushOrg, 158 
SetCapture, 58 
SetCaretBlinkTime, 95 
SetCaretPos, 94 
SetClassLong, 24 
SetClassWord, 24 
SetClipboardData, 48 
SetClip board Viewer, 54 
SETCOLORTABLE escape, 177 
SetCommBreak, 233 
SetCommEventMask, 231 
SetCommState, 229 
SetCursor, 91 
SetCursorPos, 91 
SetDlgItemInt, 43 
SetDigIltemText, 44 
SETDTR function code, 234 
SetEnvironment, 186 
SetFocus, 56 

SetMapMode, 148 

SetMenu, 61 
SetMetaFileBits, 171 
SetPixel, 123 
SetPolyFillMode, 147 
SetPriority, 207 

SetProp, 82 

SetRect, 97 

SetRectEmpty, 97 
SetRelAbs, 142 
SetResourceHandler, 216 
SetROP2, 144 

SETRTS function code, 234 
SetScrollPos, 79 
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SetScrollRange, 80 
SetSoundNoise, 238 
SetStretchBltMode, 146 
SetSysColors, 102 
SetSysModalWindow, 86 

Set TextCharacterExtra, 167 

Set TextColor, 144 

Set TextJustification, 165 

Set Timer, 59 

Set ViewportExt, 156 

Set ViewportOrg, 153 
SetVoiceAccent, 236 

Set VoiceEnvelope, 237 

Set VoiceNote, 238 

Set VoiceQueueSize, 235 

Set VoiceSound, 239 

Set VoiceThreshold, 242 

Set WindowExt, 152 

Set WindowLong, 32 

Set WindowOrg, 151 

Set WindowsHook, 103 

Set WindowT'ext, 84 
SetWindowWord, 31 

SETXOFF function code, 234 
SETXON function code, 234 
Short pointer, 6 

short type, 251 

ShowCaret, 94 

ShowCursor, 92 

SHOW_ FULLSCREEN code, 33 
SHOW_ ICONWINDOW code, 33 
SHOW_ OPENNOACTIVATE code, 33 
SHOW_ OPENWINDOW code, 33 
ShowWindow, 33 
SIMPLEREGION code, 140, 159 
Size box, 28 

Size box controls, 301 
SIZEFULLSCREEN code, 356 
SIZEICONIC code, 356 
SIZENORMAL code, 356 
SizeofResource, 216 
SIZEZOOMHIDE code, 356 
SIZEZOOMSHOW code, 356 

S_ LEGATO voice, 236 

SM_ CMETRICS index, 101 
SM_ CURSORLEVEL index, 101 
SM_ CXBORDER index, 100 
SM_ CXCURSOR index, 101 
SM_ CXDLGFRAME index, 100 
SM_ CXFULLSCREEN index, 101 
SM_ CXHSCROLL index, 100 


SM_ CXHTHUMB index, 101 
SM_ CXICON index, 101 
SM_ CXSCREEN index, 100 
SM_ CXVSCROLL index, 100 
SM_ CYBORDER index, 100 
SM_ CYCAPTION index, 100 
SM_ CYCURSOR index, 101 
SM_ CYDLGFRAME index, 100 
SM_ CYFULLSCREEN index, 101 
SM_ CYHSCROLL index, 100 
SM_ CYICON index, 101 
SM_ CYKANJIWINDOW index, 101 
SM_ CYMEWNU index, 101 
SM_ CYSCREEN index, 100 
SM_ CYVSCROLL index, 100 
SM_ CYV THUMB index, 100 
SM_ DEBUG index, 101 
SM_ FULLSCREEN index, 101 
SM_ MOUSEPRESENT index, 101 
Sound 
accent, 236 
closing, 235 
device state, 240 
functions, 235 
noise generation, 238 
notes in queue, 241 
opening, 235 
queue threshold, 241 
starting play, 240 
stopping play, 240 
synchronizing voices, 241 
threshold, 241 
voice 
envelope, 237 
frequency, 239 
queue size, 235 
threshold, 242 
wave shape, 237 
SPACEPARITY, 273 
SP_APPABORT error, 174, 175 
S_ PERIOD1024 source, 238 
S_ PERIOD2048 source, 238 
S_PERIOD512 source, 238 
S_ PERIODVOICE source, 238 
SP_ ERROR error, 174, 175 
SP_ NOTREPORTED bit, 174, 175 
SP_ OUTOFDISK error, 174, 175 
SP_ OUTOFMEMORY error, 174, 175 
SP_ USERABORT error, 174, 175 
S_ QUEUEEMPTY state, 240 
SS_ BLACKFRAME style, 304 


SS_ BLACKRECT style, 304 
SS_ CENTER style, 304 
S_SERDCC error, 239 
S_SERDDR error, 240 
S_ SERDF® error, 240 
S_SERDLN error, 239 
S_SERDMD error, 237 
S_SERDNT error, 239 
S_SERDRC error, 237 
S_SERDSH error, 237 
S_SERDSR error, 238 
S_ SERDTP error, 237 
S_SERDVL error, 237, 240 
S_ SERMACT error, 235 
S_ SEROFM error, 235 
S_ SERQFUL error, 237, 239, 240 
SS. GRAYFRAME style, 304 
SS_ GRAYRECT style, 304 
SS_ ICON style, 304 
SS_ LEFT style, 304 
SS_ RIGHT style, 304 
S_ STACCATO voice, 236 
SS_ USERITEM style, 304 
SS_ WHITEFRAME style, 304 
SS_ WHITERECT style, 304 
Stack checking option, 330 
STACKSIZE statement, 313 
STARTDOC escape, 172 
StartSound, 240 
Startup options, 320 
STATIC control class, 300 
STATIC control styles, 304 
staticX macro, 334 
S_ THRESHOLD state, 240 
Stop bits, 273 
StopSound, 240 
StretchBlt, 117 
Stretching mode 
default, 71 
retrieving; 147 
setting, 146 
Strikeout font, 262 
String messages, 351 
Strings 
ANSI to OEM conversion, 217 
conversions, 218 
examining characters, 219 
loading, 212 
lower to upper case, 218 
resource, 284 
translations, 217 
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Strings (continued) 
upper to lower case, 218 
STRINGTABLE resource, 284 
STUB statement, 318 
STYLE statement, 293 
Subclass, 25 
S_ WHITE1024 source, 238 
S— WHITE2048 source, 238 
S— WHITE512 source, 238 
S— WHITEVOICE source, 238 
SW_ OTHERUNZOOM code, 355 
SW_ OTHERZOOM code, 355 
SW_ PARENTCLOSING code, 355 
SW_ PARENTOPENING code, 355 
SYLK format, 47, 49, 51 
Symbolic Link format. See SYLK 
format 
SyncAllVoices, 241 
System 
caret. See Caret 
colors. See Color 
error message, 387 
information functions, 100 
information messages, 386 
menu box, 28, 68 
messages, 377 
metrics, 100 
modal window, 86 
timer. See Timer 
time, 387 
SYSTEM_ FONT object, 128 


Tasks, 206, 207 
TECHNOLOGY capability, 183 
Termination, 10 
Text color, 71, 144 
Text control, 296 
Text display format. See Display 
format 

TEXTCAPS capability, 185 
Text 

character spacing, 167 

color, 144 

creating fonts, 134 

drawing, 119 

extent, 166 

facename, 182 

graying, 121 

height, 166 

intercharacter spacing, 167 
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Text (continued) 

justification, 165 

line length, 166 

metrics, 183 

multiple runs, 166 

width, 166 
TEXTMETRIC data structure, 267 
TextOut, 119 
Throw, 195 
Tiled windows. See Windows, tiled 
Time, 14, 15, 387 
Timer 

functions, 55 

killing, 60 

setting, 59 
Top-level menu, 61 
TranslateAccelerator, 16 
TranslateMessage, 15 
TransmitCommChar, 228 
TRANSPARENT mode, 143 
Twips, 149 
TWOSTOPBITS, 273 
Types. See also Data structures 

BOOL, 251 

BYTE, 251 

char, 251 

DWORD, 251 

FAR, 252 

FARPROC, 252 

GLOBALHANDLE, 253 

handle, 252 

HBITMAP, 253 

HBRUSH, 253 

HCURSOR, 253 

HDC, 253 

HFONT, 253 

HICON, 253 

HMENU, 253 

HPEN, 253 

HRGN, 253 

HSTR, 252 

int, 251 

LOCALHANDLE, 253 

long, 251 

LPINT, 252 

LPMSG, 252 

LPRECT, 252 

LPSTR, 252 

NEAR, 252 

PINT, 252 

pointer, 252 


Types. See also Data structures Windows (continued) 


continued) active window, 36 
PSTR, 252 attribute functions, 84 
short, 251 border, 28 
VOID, 251 bounding rectangle, 86 
WORD, 251 bringing to top, 36 
# undef directive, 308 caption 
length, 84 


Underlined font, 262 
UngetCommChar, 228 
UnionRect, 98 

Units of measure, 148 
UnlockData, 205 
UnrealizeObject, 158 
Update rectangle, 75 
Update Window, 74 

User profile. See WIN.INI 
User-defined control, 299 
User-defined resource, 283 


ValidateRect, 76 
ValidateRgn, 77 
VARIABLE_ PITCH, 264 
Vector fonts, 431 
Version number, 195 
VERTRES capability, 184 
VERTSIZE capability, 183 
Viewport 

extents, 155, 156, 158 

moving, 156 

origin, 71, 153, 154 
Virtual keys 

codes, 419 

messages, translating, 15 

state, 56 

listed, 57, 58 
VOID type, 251 


WaitMessage, 13 
WaitSoundState, 240 


retrieving, 84 
setting, 84 
changing attributes, 31, 32 
changing size, 35 
child 
creating, 26 
enumerating, 38 
initial position, 27 
size, 27 
class 
functions, 22 
background brush, 256 
class name, 22, 256 
cursor, 255 
data structures, 254 
icon, 255 
menu, 256 
registering, 22 
replacing information, 24 
retrieving information, 23 
style, 254 
client area, 85 
closed, 37 
closing, 35 
creating, 26, 258 
destroying, 30 
disabled, 29 
displaying, 33 
enumerating, 37 
extents, 71, 152, 153, 154 
finding, 85 
flashing, 90 
functions 
class, 22 
creation, 26 


WHITE_ BRUSH object, 127 default, 21 
WHITEONBLACK mode, 146 display, 32 
WHITE_ PEN object, 128 hook, 103 


WH_ KEYBOARD hook, 103 movement, 32 
WH_ MSGFILTER hook, 103 painting, 70 
?WIN, 330 subclassing, 25 
WINDING mode, 147 height, 259 
Windows hook, 103 
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Windows (continued) 
iconic, 28 
initial position, 26 
initialization file. See WIN.INI 
messages. See Messages 
moving, 155 
name, 26, 85, 259 
opening, 34 
origin, 71, 151 
parent, 85, 259 
popup, 28 
creating, 26 
initial position, 27 
size, 27 
visibility, 37 
position, 259 
removing, 33 
retrieving information, 30, 31 
scrolling, 77 
styles, 26, 28, 259 
subclass, 25 
system modal, 86 
text, 359 
tiled, 26 
updating, 74 
visibility, 29, 36 
width, 259 
WindowFromPoint, 96 
WIN.INI 
changing, 244, 387 
colors section, 321 
contents, 319 
devices section, 322 
fonts section, 323 
functions, 222 
integers, 222 
international section, 323 
ports section, 321 
search path, 318 
strings, 223 
windows section, 320 
WinMain, 9 
WM_ ACTIVATE, 353 
WM_ACTIVATEAPP, 354 
WM_ ASKCBFORMATNAME 
message, 49, 385 
WM_ CHANGECBCHAIN, 382 
WML_ CHAR, 372 
WM_ CLEAR, 397 
WML_ CLOSE, 361 
WM_ COMMAND, 374, 401 
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WM_ COPY, 396 
WM_ CREATE, 352 

WM_ CTLCOLOR, 358 

WM_ CUT, 396 
WM_DEADCHAR, 373 

WM_ DESTROY, 30, 361 
WM_DESTROYCLIPBOARD, 382 
WM_ DEVMODECHANGE, 386 
WM_DRAWCLIPBOARD, 382 
WM_ ENABLE, 353 
WM_ENDSESSION, 362 
WM_ERASEBKGND, 357 
WM_FONTCHANGE, 386 

WM_ GETDLGCODE, 360 
WM_GETTEXT, 359 

WM_ GETTEXTLENGTH, 359 
WM_HSCROLL, 376 
WM_HSCROLLCLIPBOARD, 49, 385 
WM_ INITDIALOG, 363 
WM_INITMENU, 363 
WM_INITMENUPOPUP, 362 
WM_KEYDOWN, 370 
WM_KEYFIRST, 11, 12 
WM_KEYLAST, 11 
WM_KEYUP, 371 
WM_KILLFOCUS, 353 
WM_LBUTTONDBLCLK, 368 
WM_LBUTTONDOWN, 365 
WM_LBUTTONUP, 365 
WM_MBUTTONDBLCLK, 370 
WM_MBUTTONDOWN, 367 
WM_MBUTTONUP, 368 

WM_ MOUSEFIRST, 11, 12 
WM_MOUSELAST, 11, 12 
WM_MOUSEMOVE, 364 

WM_ MOVE, 357 
WM_NCACTIVATE, 405 
WM_NCCALCSIZE, 403 

WM_ NCCREATE, 403 

WM_ NCDESTROY, 403 
WM_NCHITTEST, 404 
WM_NCLBUTTONDBLCLK, 406 
WM_NCLBUTTONDOWN, 405 
WM_ NCLBUTTONUP, 406 
WM_NCMBUTTONDBLCLK, 408 
WM_NCMBUTTONDOWN, 407 
WM_NCMBUTTONUP, 407 
WM_NCMOUSEMOVE, 405 
WM_NCPAINT, 405 
WM_NCRBUTTONDBLCLK, 407 
WM_NCRBUTTONDOWN, 406 
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WM_NCRBUTTONUP, 407 WS_ ICONIC, 28 
WM_ PAINT, 357 WS_ POPUP, 28 
WM_PAINTCLIPBOARD, 49, 383 WS_ POPUPWINDOW, 29 
WM_ PASTE, 397 WS_ SIZEBOX, 28 

WM_ QUERYENDSESSION, 361 WS_ SYSMENU, 28 

WM_ QUERYOPEN, 352 WS_ TABSTOP, 306 

WM_ QUIT, 10, 362 WS_ TILED, 28 
WM_RBUTTONDBLCLK, 369 WS_ TILEDWINDOW, 29 
WM_RBUTTONDOWN, 366 WS_ VISIBLE, 29 
WM_RBUTTONUP, 366 WS_ VSCROLL, 28 


WM_ RENDERALLFORMATS, 382 

WM_ RENDERFORMAT, 381 

WM_SETFOCUS, 353 XON/XOFF flow control, 274, 275, 276 
WM_ SETREDRAW, 359 

WM_SETTEXT, 359 


WM_SETVISIBLE, 352 Yield, 206 
WM_SHOWWINDOW, 355 Yielding, 13, 206 
WM_ SIZE, 356 


WM_ SIZECLIPBOARD, 49, 383 
WM_ SYSCHAR, 379 
WM_ SYSCOLORCHANGE, 386 
WM_SYSCOMMAND, 380 
WM_ SYSDEADCHAR, 380 
WM_SYSKEYDOWN, 377 
WM_ SYSKEYUP, 378 
WM_SYSTEMERROR, 387 
WM_ TIMECHANGE, 387 
WML_ TIMER, 374 
WM_ USER, 351 
WML_ VSCROLL, 375 
WM_ VSCROLLCLIPBOARD, 49, 384 
WM_ WININICHANGE, 387 
WNDCLASS data structure 
defined, 254 
registering, 22 
replacing information, 24 
retrieving information, 23 
WndProc, 20 
WORD type, 251 
WriteComm, 227 
WriteProfileString, 224 
WS_ BORDER, 28 
WS_ CAPTION, 28 
WS_ CHILD, 28 
WS_ CHILDWINDOW, 29 
WS_ CLIPCHILDREN, 29 
WS_ CLIPSIBLINGS, 29 
WS_ DISABLED, 29 
WS_ DLGFRAME, 28 
WS_ GROUP, 306 
WS_ HSCROLL, 28 
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